SDK：Python 和 TypeScript

两个官方 SDK 都从同一份接口目录生成：每个接口一个有类型的方法，价格写在方法注释里；每次付费调用自动带幂等键，重试不会扣两次钱；翻页可以设花费上限。

语言	安装	要求
Python	pip install okdata	Python 3.9+，只依赖 httpx
TypeScript / JavaScript	npm install @okdata/sdk	Node 20.3+，没有运行时依赖

两个 SDK 都从环境变量 OKDATA_API_KEY 读 Key。还没有 Key？注册送试用额度。

第一次调用

from okdata import OkData

ok = OkData()  # 读取 OKDATA_API_KEY；也可以 OkData("okd_...")
page = ok.douyin.videos.search(query="露营装备", sort="latest", max_price="0.05")
for row in page.items:
    print(row["id"], row["metrics"]["likes"], row["text"][:60])
print("花费 $" + page.cost)

import { OkData } from '@okdata/sdk';

const ok = new OkData(); // 读取 OKDATA_API_KEY；也可以 new OkData({ apiKey: 'okd_...' })
const page = await ok.douyin.videos.search({ query: '露营装备', sort: 'latest', maxPrice: '0.05' });
for (const row of page.items) console.log(row.id, row.metrics.likes, row.text.slice(0, 60));
console.log('花费 $' + page.cost);

参数和 HTTP 接口同名（query、id、url、cursor……）。每个方法还接受 view（compact / standard / full，价格一样）、fields，以及 max_price（TypeScript 里是 maxPrice）：可能超过这个价的调用会在执行前被拒绝，不扣钱。新出的接口不用等 SDK 升级，按 ID 调就行：ok.call("weibo.trends.list")。

返回的是 Page（列表：items、下一页游标、是否还有）、Item（单个对象）或 Batch（一次传多个 ID：items、missing），都带 cost、扣费后余额、请求号和结果状态。

翻页，带花费上限

for page in ok.pages("douyin.videos.comments.list", id="7301234567890123456", max_pages=5, max_spend="0.01"):
    print(len(page.items), page.cost)

每一页都是单独计费的一次调用。翻下一页之前，SDK 先按这一页最多可能花多少算一遍，超过 max_spend 就停；同时把剩下的额度作为 X-Max-Price 发给服务端，贵于它的请求会被直接拒绝（不扣钱）。

重试和报错

付费调用都会自动带 Idempotency-Key，重试时沿用同一个，所以同一请求最多扣一次钱。是否重试按错误里的 retry 字段来：yes 和 same_key 会重试，once 再试一次，no 和 after_fix 不重试。错误会以 OkDataError 抛出，带错误码、说明和请求号，各错误码的含义见错误说明。

源码和其他语言

两个 SDK 都在 GitHub 上开源（MIT）。其他语言可以用 openapi.json（完整的 OpenAPI 3.1 描述）生成客户端，或者直接发 HTTP 请求：每个接口页都有可复制的 cURL 示例。

给 AI 智能体

智能体用不着 SDK：接上 MCP 服务，或者给它装 Agent Skills。在终端里干活的智能体也可以用命令行。