> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tapapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 成本控制

> 按模型、用量、张数、时长和重试控制 API 成本

API 成本主要由接口类型、模型、输入输出用量、生成张数、视频时长、工具调用、重试和批量规模决定。上线前应该先设置预算、隔离 Key 和保护阈值。

## 成本变量

| 变量         | 影响                                              |
| ---------- | ----------------------------------------------- |
| 接口类型       | 文本、图片、视频的计费变量不同                                 |
| 模型         | 不同模型单价、倍率和可用能力不同                                |
| 文本 token   | 输入、输出、`max_tokens`、缓存、音频和工具调用都会影响成本             |
| 图片 `n`     | 一次请求多张可能增加成本，最终按有效返回张数结算                        |
| 图片尺寸 / 质量  | 部分模型会按尺寸或质量调整价格                                 |
| 视频时长 / 分辨率 | 部分视频模型会按 `seconds`、`duration`、`resolution` 调整价格 |
| 工具调用       | Web Search、File Search、内置图片生成等可能产生额外费用          |
| 重试         | 失败重试需要设置上限，避免重复生成                               |
| 批量规模       | 大批量任务要先小样本验证，再放量                                |
| 并发         | 并发越高，越容易触发 429、超时和重复重试                          |
| 保存链路       | 生成成功但转存失败时，通常应重试转存而不是重生                         |
| 账户分组       | 不同账户分组可能有不同价格倍率或可用模型                            |

## 成本隔离

批量任务不要直接使用主业务 Key。建议为每个环境、活动或客户创建独立 API Key：

| 保护项    | 建议                          |
| ------ | --------------------------- |
| Key 额度 | 关闭无限额度，设置 `remain_quota` 上限 |
| 模型权限   | 开启模型限制，只允许本次任务需要的模型         |
| 过期时间   | 给临时批量任务设置过期时间               |
| IP 限制  | 服务端固定出口时可以设置 IP 白名单         |
| Key 命名 | 名称里写清业务、环境和批次，方便查日志         |
| 低余额通知  | 设置额度预警阈值和通知方式               |

平台提供 Key 额度、余额、用量日志和低余额通知。每日预算、worker 停止阈值和业务幂等需要在你的队列或后端里实现。

## 推荐做法

* 先用低成本模型跑通流程，对关键任务再切高质量模型
* 文本接口设置合理的 `max_tokens` 或 `max_completion_tokens`
* 默认关闭不需要的 Web Search、File Search 和内置图片工具
* 图片默认用 `n: 1`，确认模型支持后再使用 `n > 1`
* 视频先用短时长、低分辨率验证，再切高时长或高分辨率
* 批量任务先抽样 20-50 条真实数据
* 给每个任务记录模型和实际消耗
* 为异常重试设置最大次数
* 对请求 `n`、返回 `data.length`、保存成功数和实际消耗做对账
* 余额不足通常是 403，常见 `error.code: "insufficient_user_quota"`，不要对这类错误自动重试
* 批量任务启动前先估算预算，并设置 Key 额度上限和余额下限
* 每个任务保存 `request_id` 和 `upstream_request_id`，后续按控制台用量日志对账
* 把“生成失败”和“保存失败”拆成两个状态，避免重复生成

## 成本保护

| 风险     | 保护方式                              |
| ------ | --------------------------------- |
| 单个批次失控 | 使用独立 API Key，并设置 Key 额度上限         |
| 用错高价模型 | 开启 Key 的模型白名单                     |
| 无限重试   | 每个业务 `task_id` 设置最大重试次数           |
| 批量误触发  | 大任务先人工确认，业务侧设置每日预算                |
| 用户重复点击 | 前端按钮防重复提交，后端用业务幂等键                |
| 慢模型排队  | 降并发，必要时切换兜底模型                     |
| 输出未保存  | 只有转存成功后才把任务标记为 `succeeded`        |
| 余额耗尽   | worker 检测余额不足后停止队列                |
| 低余额未感知 | 设置额度预警通知                          |
| 价格误判   | 以控制台最终 `quota` 对账，不只看本地估算         |
| 429 风暴 | 连续 429 后自动降并发，不继续放量               |
| 超时补跑   | 先查 `request_id` 和用量日志，确认没有有效结果再补跑 |

## 批量预算模板

```text theme={null}
任务总数：
接口类型：文本 / 图片 / 视频
API Key 名称：
Key 额度上限：
默认模型：
文本 max_tokens：
是否启用 Web/File Search：
图片请求 n：
图片尺寸 / 质量：
视频时长 / 分辨率：
预计成功率：
预计单任务成本：
最大重试次数：
初始并发：
最大并发：
预算上限：
余额停止阈值：
低余额通知阈值：
```

上线前建议先跑 20-50 条真实数据，拿控制台实际 `quota` 反推平均成本和 P95 成本，再放大批量。

## 放量规则

| 阶段        | 做什么            | 通过条件               |
| --------- | -------------- | ------------------ |
| 20-50 条   | 验证参数、返回字段和保存链路 | 成功率、耗时、保存率正常       |
| 100-300 条 | 验证小批量并发和重试     | 429、5xx、timeout 可控 |
| 1000+ 条   | 分小时或分批提交       | 成本和余额变化符合预估        |

如果任一阶段出现连续 429、超时升高、`data=[]` 增多或保存失败，就先停放量，降低并发或切换模型。

## 对账指标

| 指标               | 说明                 |
| ---------------- | ------------------ |
| submitted        | 提交到业务队列的任务数        |
| requested        | 实际请求 Tapapi 的次数    |
| succeeded        | 成功拿到有效结果的任务数       |
| saved            | 成功转存到自有存储的结果数      |
| retried          | 发生重试的次数            |
| failed           | 最终失败的任务数           |
| quota            | 控制台最终消耗额度          |
| total\_tokens    | 文本或多模态模型返回的总 token |
| returned\_n      | 图片实际返回数量           |
| failed\_requests | 图片 fanout 部分失败数量   |
| task\_status     | 视频或异步任务最终状态        |

推荐每个任务至少保留：

```text theme={null}
task_id | request_id | upstream_request_id | token_name | modality | model | status | requested_n | returned_count | saved_count | total_tokens | retry_count | quota | error_type | error_code | error_message | created_at
```