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

> okdata 怎么收费：美元预付余额，按次或按条计费，调用前预扣、调用后结算，哪些情况不收费，Idempotency-Key 防重复扣费，充值规则和试用额度。

网页版：https://okdata.online/zh/docs/billing/

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

## 按次计费和按条计费

每个接口都有一个 `unit`（计费单位），接口页和[价格页](/zh/pricing/)上都写着：

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

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

## 先预扣，再结算

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

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

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

## 哪些情况不收费

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

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

## meta.billing

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

```json
"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}` 查这次调用。

```python
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 的免费额度：每个账户、每个邮箱只送一次，一次性邮箱的域名不送。第一次充值之前，账户处在试用档，限额比较低，详见[频率限制](/zh/docs/rate-limits/)。

## 查看花了多少钱

- [控制台](/zh/console/)的“调用记录”列出每次调用的请求 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` 可以直接导出成表格。

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

更新于 2026-11-12