# Finewisdom — Agent Guide

> 读这一页就够了：怎么鉴权、怎么选接口、怎么翻页、出错怎么办、花多少钱。

## 一句话

Finewisdom 是一个**社媒 + 电商数据接口平台**：15 个平台、103 个接口，全部走一个 GET，
按次计费 0.1–0.3 元，失败不扣费，注册赠 20 次。

**它解决什么**：拿到抖音/小红书/微博/B站/知乎/快手/视频号/TikTok/IG/YouTube/X 的内容与评论，
以及淘宝/京东/1688 的商品、评论、店铺数据，返回结构化 JSON。

**它不解决什么**：不做全网搜索（用搜索引擎 API）、不做验证码识别、不提供历史回溯，
微信小店（商品/GMV）没有覆盖。

## 认证

| 通道 | 方式 |
|---|---|
| REST | `?token=fw_xxx`，或 Header `X-FW-Token: fw_xxx` |
| MCP | Header `X-FW-Token: fw_xxx` |

Token 在 `https://finewisdom.top/console/` 注册后自动生成。**不要**把 token 写进代码仓库或日志。

## 调用形态

```
GET https://finewisdom.top/api?token=fw_xxx&method=douyin_video_comments&aweme_id=7624566919911230720&page=0
```

- 所有参数都是 query string
- `method` 是方法名，必须来自 `catalog.json`，不要拼造
- 分页：抖音/淘宝/京东系用 `page`（从 0 或 1 开始，见方法说明）；社媒用 `cursor` / `offset` / `start` / `max_id`
- 响应固定为 `{"status","message","data"}`；`status=success` 才计费

## 先看目录，再调用

```
GET https://finewisdom.top/catalog.json
```

返回 103 条能力，每条含 `platform`、`method`、`description`、`price_cny`、`params[]`（含 `required`）。
**免费、无需鉴权**。用它决定调哪个方法，不要凭记忆猜。

## 选接口的决策树

| 你的目标 | 调什么 |
|---|---|
| 某个抖音视频/笔记/帖子/微博的**评论** | `<平台>_*comments`，传内容 ID |
| 某条内容的**正文与互动数** | `<平台>_*detail` / `*_video` / `*_note` |
| 按关键词找内容 | `<平台>_keyword_search` / `*_search` |
| 看某个账号的资料或作品 | `<平台>_user_info` + `<平台>_user_posts` |
| 淘宝/京东商品价格与库存 | `taobao_item_get` / `jd_item_get`（传 `item_id`） |
| 淘宝/京东商品评论 | `taobao_comments` / `jd_comments` |
| TikTok 商品/店铺盘点 | `tiktok_shop_product_search` 搜商品、`tiktok_shop_seller_products` 拿店铺全量、`tiktok_shop_category_products` 按类目铺货、`tiktok_shop_product_detail` 补详情 |
| TikTok 选品 / 爆款挖掘 | `tiktok_shop_hot_products`（按站点取热卖榜，翻页传 `exclude_product_ids`） |
| 1688 找同款源头 | `item_search_1688`（关键词）或 `item_search_img_1688`（图 URL） |

## 计费与预算

- 单价 0.1–0.3 元/次，**每次调用独立计费**，翻页也算一次
- 失败、空结果**不计费**，预扣自动退回
- 大批量前先估算：`次数 × 单价`。10 万条评论 ≈ 几千次调用 ≈ 几百元
- 限流 1 次/秒/IP，批量任务请串行并留间隔，遇 `api_error` 先降速再重试

## 错误处理

| 现象 | 含义 | 怎么办 |
|---|---|---|
| `status=api_error` + 参数提示 | 方法名或参数错 | 回 `catalog.json` 核对，**不要原样重试** |
| `status=preview` | 游客模式，未充值 | 提示用户充值，不要重试 |
| 432/429 类限流 | 超过 1 次/秒 | 指数退避，保持请求不变 |
| 返回 `data` 为空 | 目标不存在或该内容已删 | 换 ID；空结果不计费，可换目标再试 |

## 常见错误

1. 把 `aweme_id` 当 `item_id` 传（抖音 vs 电商是两套 ID）
2. 用 `page` 给社媒接口翻页（社媒是 `cursor`/`offset`/`start`/`max_id`）
3. 以为 `data` 是数组——它是对象，列表通常在 `data.list` / `data.comments` 之类的字段里，先小样本看结构
4. 并发 50 个请求打 1 次/秒的限流

## MCP

`https://finewisdom.top/mcp`，Streamable HTTP，Header `X-FW-Token`。

**103 个工具，与 REST 的 103 个 method 一一对应**——工具名就是方法名，参数与 REST 完全一致。
先 `tools/list` 看有哪些工具，或读 `catalog.json` 按 `platform` + `description` 选。
所有工具只读（`readOnlyHint: true`、`destructiveHint: false`），不会修改任何平台数据。
