计费:预付余额、先预扣后结算,以及哪些不收费
okdata 怎么收费:美元预付余额,按次或按条计费,调用前预扣、调用后结算,哪些情况不收费,Idempotency-Key 防重复扣费,充值规则和试用额度。
调用费用从美元预付余额里扣。请求到了数据源的调用照常计费,返回为空、查不到或出错也一样;参数错误、余额不足这类还没请求数据源就被拦下的,一分不扣。没有订阅,默认也不会自动扣款:余额快用完了再充值就行,也可以自己开启银行卡自动充值,每次返回都写明这次花了多少、还剩多少。
按次计费和按条计费
每个接口都有一个 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,一分钱都不扣。 - 数据回来以后按实际费用结算,多预扣的部分退回余额。数据源出错或超时,按一次的价格结算(按条计费的接口算 1 条),其余退回。我们自己出错,预扣全部退回。
调用还在进行时,预扣的钱暂时不算在可用余额里,所以同时跑好几个调用,每个都要有足够的余额。有一个例外,是为了让余额不多的时候也能用:按条计费的列表接口取第一页(不带 cursor)时,如果余额付不起满页,这一页会缩到余额够付的条数,warnings 里会说明,而且这一页不会给下一页的 cursor。你在控制台给某把 Key 设的消费上限(按 UTC 日、月或总额)同样把预扣算在内,会超出上限的调用返回 402 key_budget_exceeded,不扣费。
哪些情况不收费
- 还没请求数据源就被拦下的调用:参数错误(
invalid_params)、余额不足、Key 缺失或已撤销、Key 的消费上限、频率限制(rate_limited)、超过max_price被拒、接口暂停(capability_paused)。错误返回里写着charged: false。 - 我们自己的错误(
internal_error)。 - 24 小时内用同一个
Idempotency-Key重发,拿回已保存的结果。 - 24 小时内通过
GET https://api.okdata.online/v1/calls/{request_id}/result再次读取保存的结果。 - 由结果缓存回答(
meta.cached: true)的空结果或not_found:这次没有再请求数据源。not_found的错误返回里是charged: false。 - 目录、服务状态、账户、调用记录和用量这几个路由,以及 MCP 的
find、describe和account工具。
请求到了数据源的调用,返回为空、查无此项(not_found),或者数据源出错、超时(upstream_failed、upstream_busy、timeout),都按接口的正常价格计费一次,按条计费的接口算 1 条。我们这边的内部重试不会多收,一次调用只扣一次。这时错误返回里是 charged: true 并给出 amount。估算花费时,把空结果和出错的调用也算进去。由结果缓存回答、带数据的结果,和重新读取一样按正常价格计费。settlement_unknown 见下文,全部错误码见错误码页,各接口价格见价格页。
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。满 $50 多送 3%,满 $100 多送 6%,满 $500 多送 10%,满 $1,000 多送 12%;$10 和 $25 不送。赠送的额度和充值的钱一样用。
- 累计实付满 $50 后,以后每次充值再多送 2%;满 $200 多送 4%;满 $1,000 多送 6%。这部分和上面按单笔金额的赠送叠加,一笔充值最多一共多送 18%。累计只算真付的钱:已付款的充值,加上支付争议裁定我们胜诉的;全额退款、争议败诉的不算,试用、邀请和推广送的额度也不算。档位按这笔充值之前的累计金额定,这一笔不算进去。微信、支付宝、银行卡和自动充值都适用。控制台充值页会显示已累计充值多少、再充多少升到下一档,付款前的结算明细里单独列出「累计充值多送」。
- 可以刷卡通过 Stripe 付美元(Visa、Mastercard、Amex、Apple Pay),也可以用支付宝或微信支付通过 XorPay 付人民币,汇率在付款前显示。支付宝单笔最多 ¥1,000,微信支付单笔最多 ¥20,000。
- 充值不退,余额永不过期。
自动充值
自动充值默认关闭,要自己开启。开启后,余额低于你设的那条线,就会从银行卡扣款充值,长时间跑的智能体不会因为 insufficient_balance 停下来。只支持银行卡,不支持支付宝和微信支付。
- 怎么开。 用卡充值时勾上「以后余额不足自动充值」,或者在控制台「充值与账单」页开启。在控制台开启只绑卡、不扣钱;如果开启时余额已经低于那条线,会马上扣一次。
- 三项设置。 触发线:余额低于多少时扣款,$1 到 $100 的整数,默认 $5,必须低于每次充值金额。每次充值金额:$25、$50、$100、$500 四档选一,默认 $50,照常享受充值赠送,$50 送 3%,$100 送 6%,$500 送 10%,累计充值多送也照算。每月上限:从每次金额到 $5,000,默认 $200,按 UTC 自然月计算。
- 什么时候扣。 一次调用之后余额低于触发线,或者调用因为余额不足被拒。每天最多扣 3 次,按 UTC 日计算。
- 到了每月上限。 当月不再扣款,只发一封邮件提醒;自动充值保持开启,下个月恢复。
- 邮件。 开启时发一封确认,每次扣款发收据,扣款失败或到了每月上限也会发邮件。
- 什么时候会自己关掉。 卡被拒,或者银行要求持卡人验证,自动充值会关闭并发邮件;想重新开,要重新绑卡。账户上出现信用卡争议,自动充值也会关闭。
- 怎么关。 随时可以在控制台关闭,关闭后卡会解绑,不再保存。
- 信用卡账单上的商户名称带 OKDATA 字样。
自动充值不是订阅:没有月费,只按你自己定的规则充值。
试用额度
新账户第一次登录控制台时会收到 $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"
更新于