# 价格与计费

> 美元余额按量扣费、提交前预估费用、失败自动全额退回，以及按 token 计费的视频模型怎么折算。

## 钱包扣费流程

Kerox 直接按美元从钱包余额扣费，不换算积分，也没有订阅绑定。每笔任务对应三个明确的账务状态：

1. **冻结（`cost.status: "held"`）**：调用 `POST /v1/tasks` 提交任务时，按本次参数的预估费用从可用余额中冻结对应金额。
2. **结算（`cost.status: "settled"`）**：任务成功后按实际用量结算，多冻结的部分自动退回可用余额。
3. **退回（`cost.status: "refunded"`）**：任务失败、超时或在 `queued` 阶段被取消时，冻结金额全额退回（`cost.amount: "0.0000"`）。

## 当前模型价格

下表所有数字均从模型目录配置实时计算，不写死价格。登录后或在调用 `GET /v1/models` 时带上 API Key，即可看到你账户的实际折后价。

| 模型 | ID | 计费方式 | Kerox 价格 | 说明 |
| --- | --- | --- | --- | --- |
| Seedream 5.5 | `bytedance/seedream-5.5` | 按张 | 1K/1.5K: $0.0160, 2K: $0.0280 | 比官方价低 20% |
| Seedream 5.0 Pro | `bytedance/seedream-5.0-pro` | 按张 | 1K/1.5K: $0.0360, 2K: $0.0720 | 比官方价低 20% |
| Seedream 4.5 | `bytedance/seedream-4.5` | 按张 | $0.0320 | 比官方价低 20% |
| Seedream 4.0 | `bytedance/seedream-4.0` | 按张 | $0.0270 | 比官方价低 10% |
| Seedream 5.0 Lite | `bytedance/seedream-5.0-lite` | 按张 | $0.0315 | 比官方价低 10% |
| Seedance 2.5 | `bytedance/seedance-2.5` | 按 token 计费 | 约 $0.2196 / 秒（720p） | 按 16:9、不带参考视频折算；带参考视频时单价更低 |
| Seedance 2.0 | `bytedance/seedance-2.0` | 按 token 计费 | 约 $0.1436 / 秒（720p） | 按 16:9、不带参考视频折算；带参考视频时单价更低 |
| Seedance 2.0 Fast | `bytedance/seedance-2.0-fast` | 按 token 计费 | 约 $0.0968 / 秒（720p） | 按 16:9、不带参考视频折算；带参考视频时单价更低 |
| Seedance 2.0 Mini | `bytedance/seedance-2.0-mini` | 按 token 计费 | 约 $0.0605 / 秒（720p） | 按 16:9、不带参考视频折算；带参考视频时单价更低 |

## Seedance 视频价格口径（按 token 计费）

Seedance 系列视频模型展示 **约 $X / 秒** 的价格方便估算，实际 **按 token 计费**：

- **两档费率**：
  - **不带参考视频**：按输出秒数估算的标准每秒价。
  - **带参考视频**：按「输出秒数 + 参考视频秒数」合计时长计费，单价更低。
- **Token 计算公式**：
  `token =（输出秒数 + 参考视频秒数）× 宽 × 高 × 帧率 / 1024`，宽高取请求的分辨率和画面比例。带具体帧率的公式见各模型页，以及 `GET /v1/models` 返回的 `pricing.token_formula`。
- **画面比例与声音**：每秒价按 `16:9`、不带参考视频折算；同一分辨率下，其他画面比例的费用差异在 5% 以内，开不开声音不影响价格。
- **提交前预估**：在 Studio 点击生成前会显示本次参数的预估费用；调用 API 时可以把同样的请求体发给 `POST /v1/estimate`。最后按生成结果实际用的 token 结算。

## 提交前预估费用

`POST /v1/estimate` 接收与 `POST /v1/tasks` 完全一致的请求体，不创建任务、不冻结资金，也不计入每分钟提交限流。返回的 `amount` 就是提交这次请求会冻结的金额；最终扣费取决于生成结果时（如按 token 计费的模型）`exact` 为 `false`。

```bash
curl -X POST https://api.kerox.ai/v1/estimate \
  -H "Authorization: Bearer $KEROX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.5",
    "input": {
      "content": [
        { "type": "text", "text": "a red fox running through fresh snow" }
      ],
      "resolution": "720p",
      "duration": 5
    }
  }'
```
```python
import os
import requests

resp = requests.post(
    "https://api.kerox.ai/v1/estimate",
    headers={
        "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "bytedance/seedance-2.5",
        "input": {
            "content": [
                {"type": "text", "text": "a red fox running through fresh snow"}
            ],
            "resolution": "720p",
            "duration": 5,
        },
    },
    timeout=30,
)
print(resp.json())
```
```javascript
const res = await fetch('https://api.kerox.ai/v1/estimate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KEROX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bytedance/seedance-2.5',
    input: {
      content: [
        { type: 'text', text: 'a red fox running through fresh snow' },
      ],
      resolution: '720p',
      duration: 5,
    },
  }),
});
console.log(await res.json());
```

## 充值与余额提醒

你可以在[控制台 → 钱包](/console/wallet)发起充值申请（最低 $5）：我们会在工单里回复付款方式，确认到账后余额马上更新。余额提醒邮件默认关闭，可以在[控制台 → 设置](/console/settings)里打开并设置金额；也可以随时用 `GET /v1/account` 查询余额和冻结中的金额。
