# 计费：一次调用花多少

一次成功的调用只扣一次，价格就是接口页上写的，$0.0003 起；空结果只在接口写明会收的情况下收。失败不扣费；24 小时内同一个幂等键不会扣第二次。

## 一次调用多少钱

- **按次**：一页一个价，不管里面有几条。207 个接口里有 196 个这样计价；`tiktok.videos.search` 是每次 $0.0020。
- **按条**：返回几条收几条的钱，另有每次最低和单次最高。有 11 个接口这样计价；[X 社群帖子](https://dataxapi.com/zh/apis/x/communities/posts/list/)每条 $0.0003，每次最低 $0.0003，最高 $0.0060。

价格写在三个地方：接口的页面上、`GET /v1/catalog`（每个接口的 `pricing`）、[prices.json](https://dataxapi.com/prices.json)。[价格页](https://dataxapi.com/zh/pricing/)列着全部。价格只用美元。

每次返回都在 `meta.billing` 里写明这次花了多少：

- `amount`: 这次扣了多少。
- `currency`: 固定是 `USD`。
- `balance_after`: 扣完之后的余额。

要给一次调用封顶，带上 `X-Max-Price`：可能超过它的调用在执行前就被拒（400 [`max_price_exceeded`](https://dataxapi.com/zh/docs/errors/#max_price_exceeded)）。

## 什么情况扣费

| 结果 | 返回什么 | 扣不扣 |
| --- | --- | --- |
| 完整 | 数据，`result_status: complete`。 | 扣一次。 |
| 批量里有的没取到 | 取到的在 `data.items`，没取到的在 `data.missing` 并写原因；`partial`。 | 按条的只收取到的；按次的照收一次。 |
| 列表里个别条目无效 | 无效的丢掉，`warnings` 里写明丢了几条。 | 按条的只收有效的；按次的只要有一条有效就收一次。 |
| 请求合法但没有数据 | 空的 `items`；`empty`。不要用同样的参数重试。 | 只有接口写明要收的才收（`pricing.charge_when_empty`，页面上也写着）：207 个接口里有 128 个收。 |
| 批量一个都没取到 | `empty`，要的每一个都列在 `data.missing`。 | 不扣。 |
| 对象不存在 | 404 [`not_found`](https://dataxapi.com/zh/docs/errors/#not_found)。 | 不扣。 |
| 我们或数据来源出错、超时 | 5xx，写明能不能重试。 | 不扣。用同一个 `Idempotency-Key` 重试。 |
| [`settlement_unknown`](https://dataxapi.com/zh/docs/errors/#settlement_unknown) | 极少见：结果已经保存，但确认没有传回来。 | 不知道。不能当成没扣：用同一个键再发，或者按请求号查。 |

## 幂等

1. 同一个 `Idempotency-Key`、同样的请求，24 小时内再发，返回第一次的结果，不再执行，不再扣费。
2. 同一个键、不同的请求，是 409 [`idempotency_conflict`](https://dataxapi.com/zh/docs/errors/#idempotency_conflict)。
3. 可重试的失败不保存：同键再发会重新执行。不可重试的失败（对象不存在、参数错）24 小时内同键返回同样的报错。
4. SDK 和命令行每次调用都会自己带一个键。直接发 HTTP 请求时要你自己带。

```bash
curl -G "https://api.dataxapi.com/v1/tiktok/videos/search" \
  --data-urlencode "query=space station" \
  -H "Authorization: Bearer $DATAXAPI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Max-Price: 0.002"
```

两个不收费的查询，告诉你一次调用后来怎么样了：

- `GET /v1/calls?idempotency_key=…`: 一个键现在代表什么（`state`）：`free`、`in_progress`、`settled`、`failed`、`retryable` 或 `retry_refused`。查询不会开始任何调用。
- `GET /v1/calls/{request_id}`: 一次调用的记录：`status`（`in_progress`、`settled`、`released`）和 `charged`（扣了多少）。

## 余额和充值

- 余额是预付的，没有订阅。在控制台的[账单页](https://dataxapi.com/zh/console/billing/)充值，最低 $10。
- 余额不过期。
- 充值不退。可以先用试用金（$0.10，一个邮箱一次）试，再决定充不充。
- 余额不够的调用在执行前被拒：402 [`insufficient_balance`](https://dataxapi.com/zh/docs/errors/#insufficient_balance)，带 `required`（需要多少）和 `available`（现在有多少）。超出某把 Key 自己上限的是 402 [`key_budget_exceeded`](https://dataxapi.com/zh/docs/errors/#key_budget_exceeded)。

## 用量

`GET /v1/usage` 汇总这个账户已经结束的调用，不收费。`group_by` 可以取 `day`、`capability`、`key_id`、`entry`、`source`、`end_user` 里的一个或几个；`since` 和 `until` 定时间段（不写是最近 30 天，最长 92 天）；`format=csv` 返回文件。每行有 `calls`（调用数）、`settled`（交付了的）、`charged`（扣了多少）。

```bash
curl -G "https://api.dataxapi.com/v1/usage" \
  --data-urlencode "group_by=day,capability" \
  -H "Authorization: Bearer $DATAXAPI_API_KEY"
```

---

目录修订号 c48ce454ae6c4c65。 [网页版](https://dataxapi.com/zh/docs/billing/)