# Pinterest 关键词搜索 API (pinterest.search)

- Canonical page: https://everyinfra.com/pinterest-api/search
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "pinterest", "action": "search", "params": {...}}
- Price: $0.001389 per call ($1.39 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 20, max 50 per call
- Mode: sync; add "mode": "async" for slow tasks

Pinterest 关键词搜索按 `keyword` 检索公开的 Pin，每条带标题、描述、图片、表情回应数、内容来源域名、主色调、发布时间、作者及其粉丝数，以及所在画板的名称。它回答「这个灵感主题在 Pinterest 上有哪些内容、来自哪些网站」，适合设计和内容团队收集视觉灵感，电商团队观察品类的视觉趋势，以及寻找常发这类内容的创作者。

`keyword` 填灵感或主题词，例如 Scandinavian kitchen。结果只有 Pin，不含画板和创作者资料；`content_type` 可以只看视频 Pin。`dominant_color` 是十六进制主色，汇总后可看出配色倾向；作者粉丝数为 null 表示不公开，不等于 0。

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=pinterest&action=search

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| keyword | not declared | yes | not declared | search 的灵感或主题关键词，例如 Scandinavian kitchen；检索结果类型由 content_type 选择。 |
| content_type | enum: all_pins_visual_posts / videos_video_pins | no | not declared | search 只返回 Pin：all_pins_visual_posts 保留既有参数名，但表示全部 Pin，不只限图文；videos_video_pins 仅查询视频 Pin。画板与创作者不在返回结果里。 |
| limit | integer (1–50) | no | 20 | 这次调用最多返回的条数，整数，1–50；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | 该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。 |
| url | 该记录在原平台上的可访问链接。 |
| title | 标题。平台无标题概念时（如纯文本帖）为 null。 |
| text | 正文内容，已去除 HTML 标签，全文返回、不截断（个别平台的列表结果本身只有摘要，以该平台的字段说明为准）。 |
| image_url | 图片链接。多图能力可能返回 image_urls 数组。 |
| reaction_count | 表情回应数。 |
| source_domain | 内容来源域名。 |
| dominant_color | 主色调（十六进制），做视觉分析可直接用。 |
| posted_at | 发布时间，ISO 8601 格式、UTC 时区（如 2026-08-07T12:34:56+00:00）。平台只给非标准字符串时原样透传，解析前建议做容错。null 表示平台未公开。 |
| author_username | 作者用户名（@handle），通常可用于拼 URL。 |
| author_name | 作者昵称（显示名）。 |
| author_follower_count | 作者粉丝数。null 表示不公开。 |
| board_name | 画板名称。Pinterest 的收藏单位是画板(board)。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "pinterest",
  "action": "search",
  "params": {
    "keyword": "small balcony garden"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "pinterest",
        "action": "search",
        "params": {
            "keyword": "small balcony garden",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-09-26T08:56:04Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 19. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "pinterest",
  "action": "search",
  "results": [
    {
      "id": "AZCEn6gJW6WmfANVWBfKNzZyMdukkN8LXQC2wCDzyJ-TSwvrKAEpdicrWCGZa13vjXB9mX_5ZMCOaoHOKbHGAys",
      "url": "https://www.pinterest.com/pin/AZCEn6gJW6WmfANVWBfKNzZyMdukkN8LXQC2wCDzyJ-TSwvrKAEpdicrWCGZa13vjXB9mX_5ZMCOaoHOKbHGAys/",
      "title": "Albergo Villa Cristina",
      "text": "Bei einem Aufenthalt im Albergo Villa Cristina kannst du dich auf eine Terrasse, einen Garten und einen Friseursalon freuen. Allen Gästen steht kostenloses WLAN in den Zimmern zur Verfügung. Ebenso wird dein Aufenthalt durch einen Textilreinigungsservice und eine Bar bereichert.",
      "image_url": "https://i.pinimg.com/736x/98/dd/48/98dd48792fdd03f4dc7c78daa6298a2f.jpg",
      "source_domain": "expedia.de",
      "dominant_color": "#494b3d",
      "posted_at": "2026-08-26T11:34:34+00:00",
      "author_username": "•••",
      "author_name": "•••",
      "author_follower_count": 67097,
      "board_name": "Hotels",
      "platform": "pinterest"
    },
    {
      "id": "AXNGx7QQOfcPd0u8HtCj1KEsTf7bOCdITrT644VKab5YezQbjPSmyCi4PqorYMUIIBKxCExIUMDP-az0fUCpCHk",
      "url": "https://www.pinterest.com/pin/AXNGx7QQOfcPd0u8HtCj1KEsTf7bOCdITrT644VKab5YezQbjPSmyCi4PqorYMUIIBKxCExIUMDP-az0fUCpCHk/",
      "title": "2 BTK TERRACE RETREAT BY Lavanya",
      "text": "2 BTK TERRACE RETREAT BY Lavanya  bietet Annehmlichkeiten wie eine Terrasse und eine Wäscherei. Kostenloses WLAN in den öffentlichen Bereichen sorgt dafür, dass du auch vor Ort stets in Verbindung bleiben kannst.",
      "image_url": "https://i.pinimg.com/736x/22/b0/51/22b051539eef2a5908c005ac6b3a178d.jpg",
      "source_domain": "expedia.de",
      "dominant_color": "#ccb08d",
      "posted_at": "2026-07-13T07:16:34+00:00",
      "author_username": "•••",
      "author_name": "•••",
      "author_follower_count": 67097,
      "board_name": "Hotels",
      "platform": "pinterest"
    }
  ],
  "count": 19,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### `content_type` 两个取值有什么区别？

`all_pins_visual_posts` 是保留下来的参数名，实际表示全部 Pin，不只是图文；`videos_video_pins` 只查视频 Pin。两个取值返回的都是 Pin，画板和创作者不在这个能力的返回范围内。

### 怎么从搜索结果找到作者的更多内容？

`author_username` 是作者的用户名：传给 Pinterest 用户内容可以读他发布的 Pin，传给 Pinterest 画板列表可以看他的画板。这两个能力都接受用户短名，开头可以带 @，但不解析完整主页链接。

### 搜索结果里有转存数吗？

没有。搜索结果带 `reaction_count`（表情回应数），不带转存数和评论数。需要这些数据时，用 Pinterest 单条 Pin 读取这条 Pin 的详情，传含 /pin/数字ID/ 的 Pin 链接。

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=pinterest
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
