通用约定
异步任务模型、状态轮询、计费规则与错误码
异步任务模型
绝大多数生成类接口都是异步的：
POST 创建任务 → 返回 task_id
GET 查状态 → 轮询 status，直到 completed / failedflowchart LR
A[POST 创建] --> B(task_id)
B --> C{GET 轮询 status}
C -- processing --> C
C -- completed --> D[拿结果 URL]
C -- failed --> E[看 error]状态枚举
对外统一暴露 4 个状态（各模型上游的原始状态会映射到这几个）：
| status | 含义 | 客户端怎么办 |
|---|---|---|
pending / queued | 已接收，排队中 | 继续轮询 |
processing | 处理中 | 继续轮询 |
completed / succeeded | 完成 | 取结果 URL |
failed | 失败 | 看 error / errorMessage |
轮询建议
提交后 2 秒 → 第一次查状态
之后 → 每 3–5 秒一次
视频/播客 → 最长可能数分钟计费
- 按字符（音频）：CJK 字符记 2，其他记 1；部分能力有最低消费（如语音设计 ≥10）。
- 按秒（视频）：
每秒费率 × 时长，向上取整。 - 固定：部分模型按次固定计费。
- 失败退款：任务失败时自动退还已扣积分（Seedance、Sora2、短剧等）。
- 积分在任务完成时结算，失败不扣费。
错误码
| HTTP | 场景 |
|---|---|
400 Bad Request | 缺必填字段 / 参数格式错误 |
401 Unauthorized | 缺少或无效的 API Key |
402 Payment Required | 积分不足 |
404 Not Found | task_id 不存在 |
429 Too Many Requests | 并发超限 |
5xx | 服务端异常（看 message） |
{ "error": "insufficient_credits", "message": "Not enough credits." }分页
列表类接口统一用：
| 参数 | 说明 |
|---|---|
page / offset | 页码 / 偏移 |
limit | 每页条数 |
total（响应） | 总条数 |