计费：预付余额、先预扣后结算，以及哪些不收费

调用费用从美元预付余额里扣。成功的调用按标价扣，失败的调用一分不扣。没有订阅，也不会自动续费：余额快用完了再充值就行，每次返回都写明这次花了多少、还剩多少。

按次计费和按条计费

每个接口都有一个 unit（计费单位），接口页和价格页上都写着：

call：每次请求一个价，不管返回几条。抖音视频评论一页 $0.002，这一页只有 3 条还是满 20 条，价格都一样。
item：单价乘以返回的条数，单次不低于接口的 minimum（最低消费），也不超过它的 maxCharge（单次上限）。X 账号搜索每个账号 $0.0004，满页 20 个账号是 $0.008，空页按 1 条收。

写脚本的话，可以直接读 /prices.json，里面的 unit、price、minimum、max_charge 就是这些数字。

先预扣，再结算

每次付费调用都按同样的步骤走：

去平台取数之前，先从余额里预扣这次最多可能花的钱：按次计费的接口预扣一次的单价；按条计费的列表接口预扣满一页的钱；按条计费的查询接口按你要查的 id 个数预扣，最多到单次上限。
余额不够预扣，调用就到此为止，返回 402 insufficient_balance，一分钱都不扣。
数据回来以后按实际费用结算，多预扣的部分退回余额；调用失败则全部退回。

调用还在进行时，预扣的钱暂时不算在可用余额里，所以同时跑好几个调用，每个都要有足够的余额。有一个例外，是为了让余额不多的时候也能用：按条计费的列表接口取第一页（不带 cursor）时，如果余额付不起满页，这一页会缩到余额够付的条数，warnings 里会说明，而且这一页不会给下一页的 cursor。你在控制台给某把 Key 设的消费上限（按 UTC 日、月或总额）同样把预扣算在内，会超出上限的调用返回 402 key_budget_exceeded，不扣费。

哪些情况不收费

所有报错。错误返回里写着 charged: false，超时、平台故障、参数错误、触发频率限制都一样，大多数接口的 not_found 也是。例外有两个：少数对查无此项收费的接口（见下一节），这时 not_found 的返回里是 charged: true 并给出 amount；以及下文的 settlement_unknown。全部错误码见错误码页。
24 小时内用同一个 Idempotency-Key 重发同一个调用。
一个都没查到的批量调用。
24 小时内通过 GET https://api.okdata.online/v1/calls/{request_id}/result 再次读取保存的结果。
目录、服务状态、账户、调用记录和用量这几个路由，以及 MCP 的 find 和 describe 工具。

空结果和“查无此项”收不收费，由每个接口单独规定。大多数接口查无此项不收费，空结果照常收费（按条计费的接口收 1 条或最低消费），因为平台确实被问到并且给了回答。少数抖音接口正好反过来，比如抖音巨量算数品牌指数趋势。价格页里每个平台的价格表都列着这两项，/prices.json 里每个接口也都有 charge_when_empty 和 charge_when_not_found 两个字段。

meta.billing

每次成功的返回都带着这次的账单：

"billing": { "amount": "0.02", "currency": "USD", "balance_after": "9.98" }

amount 是这次调用的费用，balance_after 是结算之后的余额，单位都是美元，格式是十进制字符串。自己累加时请按十进制计算，不要转成浮点数，否则会出现舍入误差。

Idempotency-Key

在请求头里带上 Idempotency-Key，值是 1 到 255 个可见 ASCII 字符（用 UUID 就行），在拿到结果之前和请求一起保存好。它属于账户，同一账户下的所有 Key 共用。

24 小时内用同一个 key 发同一个请求，会直接返回保存的结果：meta.replayed: true，amount: "0"，响应头带 Idempotent-Replayed: true。
同一个 key 换了请求内容，返回 409 idempotency_conflict；第一次调用还没跑完就重发，返回 409 call_in_progress，稍等一下用同一个 key 再试。
not_found 和 invalid_params 这两种结果会记在这个 key 上，24 小时内重发还是同样的回答；其他失败会把 key 放开，重发会重新执行一次。
settlement_unknown（charged: null）表示数据已经拿到，但没能确认扣费是否完成。用同一个 key 重发，可以拿到这份结果，而且不会重复扣费；也可以用 GET https://api.okdata.online/v1/calls/{request_id} 查这次调用。

import os
import uuid
import requests

URL = "https://api.okdata.online/v1/douyin/videos/comments/list"
key = str(uuid.uuid4())  # 这个请求的每次重发都用它
headers = {"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}", "Idempotency-Key": key}

body = requests.get(URL, headers=headers, params={"id": "7301234567890123456"}, timeout=60).json()
if body["code"] == "ok":
    bill = body["meta"]["billing"]
    print("本次", bill["amount"], "余额", bill["balance_after"], "重放", body["meta"]["replayed"])
else:
    print(body["code"], "扣费:", body["charged"], body["message"])

价格表版本

所有价格属于一个价格表（price book）。任何一个接口的计费单位、单价、最低消费、单次上限，或者空结果、查无此项的收费有变动，价格表的版本号就会变。/prices.json 里叫 price_book（生效时间记录下来以后还有 effective_at），GET https://api.okdata.online/v1/catalog 里叫 priceBook。建议把版本号和你的成本估算存在一起，发现版本变了就重新读一遍价格。

充值

每次充值是整数美元，最少 $10，最多 $10,000。满 $100 多送 10%，满 $500 多送 20%，赠送的额度和充值的钱一样用。
可以刷卡通过 Stripe 付美元（Visa、Mastercard、Amex、Apple Pay），也可以用支付宝或微信支付通过 XorPay 付人民币，汇率在付款前显示。支付宝单笔最多 ¥1,000，微信支付单笔最多 ¥20,000。
充值不退，余额永不过期。

试用额度

新账户第一次登录控制台时会收到 $0.10 的免费额度：每个账户、每个邮箱只送一次，一次性邮箱的域名不送。第一次充值之前，账户处在试用档，限额比较低，详见频率限制。

查看花了多少钱

控制台的“调用记录”列出每次调用的请求 ID、状态和费用，可以按接口、状态和日期筛选；“充值与账单”里有充值记录和按平台统计的花费。
GET https://api.okdata.online/v1/account 返回余额和当前这把 Key 的消费上限，免费。
GET https://api.okdata.online/v1/calls/{request_id} 告诉你一次调用是 settled（已结算）还是 released（已退回），以及 charged 了多少。
GET https://api.okdata.online/v1/usage?group_by=day,capability 汇总最近 30 天（最多 92 天）的调用次数和费用，加上 format=csv 可以直接导出成表格。

curl -s "https://api.okdata.online/v1/account" -H "Authorization: Bearer $OKDATA_API_KEY"