请求与返回

路径和方法

每个接口的地址是 https://api.okdata.online/v1/ 加上把点换成斜杠的接口 id。douyin.videos.comments.list 就是 GET https://api.okdata.online/v1/douyin/videos/comments/list。参数放在查询字符串里。需要传列表（ids、keywords）的接口改用 POST 和 JSON 请求体，接口页会写明。

鉴权

把 key 作为 Bearer token 发送：

Authorization: Bearer okd_...

key 绝不放进 URL。目录、状态接口以及 MCP 的 find、describe 工具不需要 key。

统一返回结构

所有成功返回都是同一个外层结构：

{
  "code": "ok",
  "request_id": "0f6c2a8e-4b1d-4e0a-9a51-3c7d2b9e1f20",
  "data": { "items": [] },
  "page": { "next_cursor": "eyJvIjoyMH0", "has_more": true },
  "warnings": [],
  "meta": {
    "capability": "douyin.videos.search",
    "billing": { "amount": "0.004", "currency": "USD", "balance_after": "9.996" },
    "unavailable": { "metrics.views": "platform" },
    "cached": false,
    "replayed": false,
    "fetched_at": "2026-11-11T08:00:00Z"
  }
}

列表接口返回 data.items 和 page；单对象接口返回 data.item，没有 page。
meta.billing.amount 是这次调用的费用，美元，十进制字符串。算钱请按十进制处理，不要转成浮点数。
meta.unavailable 列出每个为 null 的字段和原因：platform（平台本来就不展示）或 capability（暂时取不到）。
meta.cached 为 true 表示结果来自短期缓存；meta.fetched_at 是从平台读取数据的时间。

翻页

一次调用返回一页。要下一页，就把 page.next_cursor 原样作为 cursor 传回。page.has_more: false 表示已经取完。每一页都单独计费，够用了就停：

import os
import requests

URL = "https://api.okdata.online/v1/douyin/videos/comments/list"
HEADERS = {"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"}

def comments(video_id, max_pages=5):
    cursor = None
    for _ in range(max_pages):
        params = {"id": video_id, **({"cursor": cursor} if cursor else {})}
        body = requests.get(URL, headers=HEADERS, params=params, timeout=60).json()
        if body["code"] != "ok":
            raise RuntimeError(body["message"])
        yield from body["data"]["items"]
        if not body["page"]["has_more"]:
            return
        cursor = body["page"]["next_cursor"]

抖音评论翻五页就是五次调用：$0.01。

view 和 fields

返回太长，模型读起来就费 token。两个参数可以精简：

view=compact 每个对象返回更少的字段，standard 是默认值，full 会在 ext 里加上平台特有字段。
fields=id,text,metrics.likes 只保留你列出的字段，嵌套字段用点连接。

两者都不影响价格。

安全重试

每次调用都带上 Idempotency-Key 请求头，内容是一个你和请求一起保存的随机字符串。24 小时内用同一个 key 重发同一个请求，会直接返回保存的结果（meta.replayed: true），不再扣费。同一个 key 换了请求内容会被拒绝，返回 invalid_params。遇到 rate_limited 等 retry_after_seconds 秒；遇到 not_found 不要重试。全部情况见错误码页。