给 AI

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

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 就是这些数字。

先预扣,再结算

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

  1. 去平台取数之前,先从余额里预扣这次最多可能花的钱:按次计费的接口预扣一次的单价;按条计费的列表接口预扣满一页的钱;按条计费的查询接口按你要查的 id 个数预扣,最多到单次上限。
  2. 余额不够预扣,调用就到此为止,返回 402 insufficient_balance,一分钱都不扣。
  3. 数据回来以后按实际费用结算,多预扣的部分退回余额。数据源出错或超时,按一次的价格结算(按条计费的接口算 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"

更新于

接上一次,以后直接问 AI。

新 key 自带 $0.10 试用额度。贴一句话,就能接进你的智能体。

免费开始
一句话接进你的 AI

把这句话发给你的智能体

读一下 https://okdata.online/zh/agents.md,帮我把 okdata 配好;我的 key 在环境变量 OKDATA_API_KEY 里。

Claude Code、Cursor、Codex 等能打开网址的智能体,读完会自己配好。

MCP 地址https://api.okdata.online/mcp