> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 账户与计费

> 余额、额度、退款、用量统计，以及请求频率额度如何随充值提升。

# 账户与计费

## 怎么计费

一个账户一份美元余额，随工作完成而扣减。没有订阅、没有月度承诺 —— 先充值，后消耗。

* **文本**按 token 计量，输入、缓存输入、输出分别定价。
* **任务**（图片、视频、特效、工作流）在提交时预扣、完成时结算。

## 在哪看花了多少

两个地方，数据同源：

* [控制台](https://beatapi.io/dashboard)，可看调用次数、token、费用与按密钥的明细。
* `GET /v1/usage`，同样的数据可编程获取 —— 包含 `by_model`、`by_capability`、`by_api_key`。

## 任务失败了怎么算

**预扣会退回。** `GET /v1/tasks/{task_id}` 会在任务上体现退款，`GET /v1/usage` 会把 `credits_refunded` 与 `credits_settled` 分开列出。

这一点对你自己的账务很重要：**如果你的账本只记预扣、从不读退款，数字迟早和账单对不上。** 两边都要对。

## 余额为什么会是负数

`credit_balance` 可以低于零。长任务在完成时才结算，所以已经受理的工作会跑完并计费，即使中途余额已经归零。充值后余额会回到正数。

## 余额归零会怎样

账户上所有付费操作开始返回 `402 insufficient_credits` —— **这是账户级的，不是按密钥算的**。余额大于零但低于本次请求的价格时，同样返回 `402`。已受理的任务会继续跑完。不会删除任何数据，也不会吊销任何密钥；充值后立即恢复。

带有自身额度的密钥把额度用尽是另一回事：它返回 `401 invalid_api_key`，错误信息会写明密钥额度已用尽，账户上的其他密钥照常可用。在控制台创建的密钥没有自身额度，换用这样的密钥即可。

如果你有面向用户的服务，请对 `402` 配告警，别等用户来告诉你。

## 请求频率额度是怎么定的

**按累计已付充值额，而不是按套餐。** 充值会让账户永久升到更高档位 —— 档位只升不降，因为它依据的那个数字只增不减。

当前额度与下一档位在控制台可见，也在 `GET /api/user/self` 的 `rate_limit` 里：

```jsonc
"rate_limit": {
  "enabled": true,
  "window_minutes": 1,
  "success_count": 20,
  "next_tier": { "min_topup_quota": 50000000, "success_count": 30 }
}
```

有两点是刻意不体现的：**赠送额度与邀请奖励不计入档位**；这里显示的数字也**不包含**单把密钥自身可能设置的更严限制。

免费模型（「免费模型」分类，例如 `jev-1.14-free`）不走这套档位，而是有单独的固定账户限额：首次充值前每分钟成功 1 次；任意金额充值后每分钟最多 10 次，与充值多少无关。它与上面的档位分开计算，免费调用不会占用付费额度；超出限额的请求返回 `429` 并带 `Retry-After`。

## 额度会过期吗

不会。余额一直保留到用完为止。

## 同样的提示词为什么价格不一样

四个原因，按最常让人意外的顺序：

1. **输出长度会变。** 输出是文本调用里贵的那一半，而不设上限时长度由模型决定。
2. **缓存输入比新鲜输入便宜。** 重复一段长系统提示词可能命中缓存，只花首次调用的一小部分。
3. **有些模型按时段计价。** DeepSeek 的两个高缓存版（HC）模型在工作日北京时间 09:00–12:00、14:00–18:00 翻倍，常规付费 DeepSeek 模型全天同一价；混元 `hy3` 有自己的每日窗口。具体时段见[价目页](https://beatapi.io/pricing)脚注。
4. **有些模型按上下文长度计价。** GPT-5.6 与 Grok 系列在超过阈值后按更高档位计费。长会话会在无声无息中越线。

每次响应的用量记录都会显示实际适用的档位。

## 能按应用分别看成本吗

**给每个应用发一把独立密钥。** `GET /v1/usage` 的 `by_api_key` 就会按密钥归集任务数与额度消耗，不需要你做任何额外工作。

## 怎么充值

在[控制台](https://beatapi.io/dashboard)充值。支付确认后余额立即更新，之后不需要再启用什么。

## 对某笔扣费有疑问

在[控制台](https://beatapi.io/dashboard)提交工单，附上该次调用的 `request_id` 或任务编号，两者都能定位到唯一一条记录。