---
title: "快速开始 · 文档 · SocialToAI"
canonical: https://socialtoai.app/zh/docs/
updated: 2026-11-20
---

# 快速开始

> socialtoai.app 的公开 REST API 和 MCP 尚未开放。登录后可在控制台生成小红书评论报告。

SocialToAI 是一个让 AI 工具读取社交媒体上公开可见内容（帖子、评论、账号、热榜）的 API 和 MCP 服务，覆盖 TikTok、Instagram、X、Reddit、YouTube、小红书、抖音、微博 等 18 个平台。按预付积分计费，失败不扣。

- 页面：https://socialtoai.app/zh/docs/
- 最近更新：2026-11-20

拿到 Key，发一次调用，接进你的 AI。这一页的每一步，用注册送的 100 积分就能做完。

- REST: `https://socialtoai.app/v1/<action>`
- MCP: `https://socialtoai.app/mcp`

### 事实表

- 平台（18 个）：TikTok、Instagram、X、Reddit、YouTube、Facebook、LinkedIn、Threads、Telegram、Pinterest、小红书、抖音、微博、公众号、B 站、知乎、快手、视频号
- 广告库（2 个）：Meta 广告库、Google 广告透明度中心
- 动作（6 个）：search、trending、detail、comments、user_profile、user_posts，另有平台独有接口目录（find / call）
- 工具（7 个）：品牌口碑、评论分析、账号动态、找达人、达人档案、批量链接数据、爆款发现
- API：https://socialtoai.app/v1 · MCP（Streamable HTTP）：https://socialtoai.app/mcp · 认证：ChatGPT、Claude、Claude Code、Codex 和 Cursor 登录授权（OAuth）；脚本和服务器在请求头里放 API Key
- 不带 Key 可用：capabilities、find、OpenAPI
- 价格：$10 = 3,000 积分 · $50 = 20,000 · $200 = 100,000 · $10 到 $2,000 的任意整数金额
- 每次调用：多数调用 2 积分（范围 1–102）；低至每次 $0.002
- 免费：注册送 100 积分、不用绑卡；积分不过期、不订阅、不退款。
- 计费：成功的调用扣费，搜索正常但没搜到照扣；查不存在的对象、数据来源对这种查询照常收费时也按价扣（返回里写明）。失败不扣。
- 限制：每把 Key 每秒 5 次，首次购买后每秒 20 次
- 支付：银行卡或支付宝，以美元计价
- 数据：平台上公开可见的内容和账号信息；评论者一律匿名
- 更新：2026-11-20 · 价格版本 pv_0f22059fed3e

## 1. 拿到 Key

用 Google 或邮箱登录 (https://socialtoai.app/zh/sign-in/)，邮箱登录时我们会发一个一次性验证码，不用设密码。新账户自带 100 积分，不用绑卡。

在控制台打开 API Key 页，创建一把 Key。它以 `stai_live_` 开头，只显示一次，请当场复制，然后放进环境变量：

**终端**

```
export SOCIALTOAI_API_KEY="<YOUR_API_KEY>"
```

> **别让它外泄** 把 Key 放在 `Authorization` 请求头里。像对待密码一样对待它：不要发进聊天、截图和共享的代码。泄露了就在控制台撤销，再新建一把。

## 2. 发第一次调用

每个动作都是向 `https://socialtoai.app/v1/<action>` 发一个 `POST`，请求体是 JSON。下面这个是 `/v1/search`，平台是 LinkedIn：按关键词找帖子：正文、作者、点赞数、评论数和发布时间。

**cURL**

```
curl https://socialtoai.app/v1/search \
  -H "Authorization: Bearer $SOCIALTOAI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "linkedin",
    "query": "AI SDR"
  }'
```

**Python**

```
import os
import uuid
import requests

response = requests.post(
    "https://socialtoai.app/v1/search",
    headers={
        "Authorization": f"Bearer {os.environ['SOCIALTOAI_API_KEY']}",
        # A new key for each request; the same one again retries it without paying twice.
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "platform": "linkedin",
        "query": "AI SDR",
    },
)
print(response.json())
```

返回是这样的：

**返回** (200 OK, 2 积分)

```
{
  "status": "ok",
  "action": "search",
  "platform": "linkedin",
  "items": [
    {
      "platform": "linkedin",
      "type": "content",
      "url": "https://www.linkedin.com/posts/adamschoenfeld_ai-sdrs-had-a-false-start-now-theres-a-activity-7519050542090768384-UK-T",
      "text": "The first wave was overhyped back in 2023-2024. We all got sick of the \"replace humans\" pitches, the over-prom",
      "metrics": {
        "likes": 234,
        "comments": 93,
        "views": null
      }
    },
    {
      "platform": "linkedin",
      "type": "content",
      "url": "https://www.linkedin.com/posts/ashleyekramer_the-best-way-to-understand-where-agents-add-activity-7505733465905152000-xKuc",
      "text": "At ElevenLabs, we started with inbound qualification. Leads can choose to speak with Dom, our AI SDR, and get",
      "metrics": {
        "likes": 536,
        "comments": 28,
        "views": null
      }
    },
    {
      "platform": "linkedin",
      "type": "content",
      "url": "https://www.linkedin.com/posts/jasonmlemkin_if-you-hook-up-an-ai-sdr-and-go-away-and-activity-7344825206001082368-Cqhd",
      "text": "If you hook up an AI SDR and go away and do nothing, you will get nothing. Zilch. Nada. Nothing. Will fail. If you hook up a",
      "metrics": {
        "likes": 113,
        "comments": 41,
        "views": null
      }
    }
  ],
  "cost_credits": 2
}
```

_一次真实调用，录制于 2026-10-30：返回的 10 条里的 3 条，只列这几个字段，正文只留开头。每条的全部字段见返回格式页。_

> **值得知道** 这次调用扣了 2 积分。每个返回的末尾都有 `billing`，你和你的 AI 随时知道花了多少、还剩多少。

## 3. 通过 MCP 接进你的 AI

如果你在 AI 客户端里工作，根本不用自己写请求。在你的 AI 里添加 MCP 服务器，填这个地址：`https://socialtoai.app/mcp`。弹出登录页就用邮箱登录、点“允许”；需要填 Key 的工具，把刚才那把 Key 放进请求头：`Authorization: Bearer <YOUR_API_KEY>`。

在终端里运行命令。Claude Code 然后在 Claude Code 里输入 /mcp，选 socialtoai，登录：

**Claude Code**

```
claude mcp add --transport http socialtoai https://socialtoai.app/mcp
```

**Codex**

```
codex mcp add socialtoai --url https://socialtoai.app/mcp
```

之后用大白话直接问。你的 AI 会自己选调用，并告诉你花了多少。[按客户端看详细步骤](https://socialtoai.app/zh/mcp.md)。

## 4. 看懂返回的结构

所有平台、所有动作都返回同一种结构。把这几部分看懂一次，18 个平台，另有 2 个广告库都能读。平台给不了的字段返回 `null`。

| 部分 | 说明 |
| --- | --- |
| `request_id`, `action`, `platform`, `status` | 调了什么，成没成功。 |
| `items` | 结果列表。同一种对象在所有平台上用同一套字段名。 |
| `unavailable` | 这个平台给不了的字段，它们在每一条里都是 `null`。 |
| `page` | `has_more` 为 true 时，把 `cursor` 原样发回取下一页。 |
| `billing` | 这次扣了多少积分，以及扣完后的余额。 |

[返回格式](https://socialtoai.app/zh/docs/api/response.md) 列出了外层结构和每种对象的全部字段。

## 5. 出错与不扣费

失败不扣。查到了就扣；正常查询但没有结果也算一次；个别接口查不存在的对象也收费，返回里会标 `charged: true`。执行前就被我们拒绝的请求返回 HTTP 错误状态码；平台那边出的问题仍然是 HTTP `200`，返回体里带 `status` 和 `error`，`cost_credits` 为 `0`。每个错误都带 `request_id` 和 `fix`，后者说明怎么改。

| 代码 | HTTP | 发生了什么，怎么办 | 重试 | 扣费 |
| --- | --- | --- | --- | --- |
| `invalid_params` | 400 | 缺少参数，或参数不对。 没有执行。按返回里的 `fix` 改正。 | 不用 | 不扣 |
| `unauthorized` | 401 | Key 缺失、不对、已到期或被暂停。 在请求头里带上有效的 Key；`reason` 说明是哪种情况。 | 不用 | 不扣 |
| `insufficient_balance` | 402 | 余额不够这次调用。 没有执行。购买积分后再发一次。 | 不用 | 不扣 |
| `not_found` | 200 / 404 | 内容或账号不存在、是私密的，或已删除；平台说了原因时 `why` 写明是哪一种，`platform_says` 是平台的原话。来源对这次查询照常收费的接口按价扣费，报错带 `charged: true`。 不用重试。路径写错时也返回这个代码。 | 不用 | 来源收费时按价扣 |
| `daily_limit_reached` | 429 | 每日上限已到。 没有执行。上限设在 Key 或账户上，到 `resets_at` 重新开始。 | 不用 | 不扣 |
| `rate_limited` | 429 | 这把 Key 每秒调用太多，或同时在跑的太多。 等 `Retry-After` 之后再发。 | 可以 | 不扣 |
| `temporarily_unavailable` | 200 / 503 | 这个调用暂时停用。 状态页会说明原因，稍后再试。 | 可以 | 不扣 |
| `invalid_target` | 200 | 链接或编号指向的目标无效。 检查 `fix.param` 指出的那个值。 | 不用 | 来源收费时按价扣 |
| `upstream_error` | 200 | 这次没有从平台取到结果，我们这边已经试过最多三次。 `retryable` 为 true 时，等 `retry_after_seconds` 秒再发一次；同一个请求又失败，多半是内容本身取不到，换一个输入。 | 视情况 | 不扣 |
| `timeout` | 200 | 没有按时拿到结果，也无法确定是否执行过。成本由我们承担。 我们不会自动重试（`X-Should-Retry: false`）。还需要的话请发起新请求。 | 不用 | 不扣 |

> **值得知道** 这不算出错：搜索正常执行，只是没搜到。`status` 是 `empty`，`items` 为空，照常扣费。

[错误](https://socialtoai.app/zh/docs/api/errors.md) 页列出了全部代码和每种情况。

## 接下来

- [API 参考](https://socialtoai.app/zh/docs/api/search.md)：6 个动作、它们的参数和每次调用的积分。
- [通过 MCP 接入](https://socialtoai.app/zh/mcp.md)：所有客户端同一个地址，以及每个客户端的步骤。
- [认证](https://socialtoai.app/zh/docs/authentication.md)：AI 应用怎么登录授权，Key 放在哪里，不带 Key 能做什么。
- [积分与计费](https://socialtoai.app/zh/docs/credits-and-billing.md)：积分是什么、每次调用多少、什么时候不扣。
- [定期运行](https://socialtoai.app/zh/docs/schedules.md)：让同一个请求每天或每周定时运行，带上限。
- [Webhooks](https://socialtoai.app/zh/docs/webhooks.md)：运行完成时收到一条签名的消息，不用反复来查。
- [批量任务](https://socialtoai.app/zh/docs/batches.md)：一个任务在后台读最多 2,000 条链接。
