计费
成功才扣费,每次返回的 meta.billing 和响应头 X-Charged 都写明扣没扣钱。完整价格见定价。
什么时候扣费
- 成功取到数据:按接口标价扣一次
- 搜索的空结果:也扣(空结果也是一个答案)
- 热榜是空的:不扣,按平台出错处理,可以重试
- 其他接口没取到数据、对象不存在:不扣
- 参数错误、平台出错、超时:不扣
- 列表每页单独扣
按条计费
少数接口(x.posts.quotes.list、x.users.mentions.list、x.posts.thread.list、x.users.search)按返回的条数收费:每条单价 × 条数,每次不低于下限、不高于上限,价格写成「$0.0003/条(每次 $0.0003–0.006)」。调用时先按上限预扣,拿到结果后按实际条数扣,多的马上退回。返回的 meta.billing 里 unit 是 item,items 是这次的条数,amount 是实际扣的钱。用 X-Max-Price 时按上限比较。
X-Max-Price
在请求头里写你这次最多愿意付多少美元,价格超过就不调用、不收费:
X-Max-Price: 0.01
Idempotency-Key
网络断了要重试时,带上同一个 Idempotency-Key。24 小时内同一把 Key、同一个 Idempotency-Key、同一个请求只算一次,第二次直接返回第一次的结果(响应头 Idempotent-Replayed: true)。同一个 Idempotency-Key 用在不同请求上会返回 409。
Idempotency-Key: 3b8c4d2e-…
花费上限
在控制台给每把 Key 设上限,花到上限后这把 Key 的调用返回 key_spend_cap_reached,其他 Key 不受影响。
余额不足
返回 402 insufficient_balance,带 top_up_url。脚本和 AI 遇到它应该停下来,不要反复重试。