密钥与接口地址
“密钥与接口地址”章节在账户 → API创建密钥。完整密钥只在创建时展示，请立即妥善保存；列表只展示用于辨认的前缀。仅查询可以使用只读权限，上传和提交处理需要写入权限。
开放 API 基础地址为 https://app.berserkapi.cn/api/v1，请求头使用 Authorization: Bearer YOUR_API_KEY。API Key 仅适用于 /api/v1，不能访问账户或管理员接口。密钥应保存在自己的服务器上，不要写入公开的浏览器代码。
curl 'https://app.berserkapi.cn/api/v1/tools' -H "Authorization: Bearer $GLACIER_API_KEY"返回值包含当前工具、参数、限制和价格，请读取这些值，不要写死单价或依赖引擎的选项。
完整处理流程
“完整处理流程”章节GET /api/v1/assets/upload-limits获取上传限制。POST /api/v1/assets/uploads申请上传凭证。按返回的方法和字段，把文件传到返回的存储 URL；仅向应用 API 发送 API Key。POST /api/v1/assets/{assetId}/complete确认上传完成，等待素材就绪。POST /api/v1/tasks/quote获取报价，提交所选assetId、toolId和params。problem非空表示当前不能提交。POST /api/v1/tasks提交同样的选择，携带有效报价 ID，并设置唯一的Idempotency-Key请求头。- 按响应中的
Location或urls.status查询状态，遵守Retry-After，直到进入终态。 - 成功后调用
GET /api/v1/tasks/{taskId}/result获取输出链接或报告。
重试与费用控制
“重试与费用控制”章节同一次逻辑提交的网络重试必须复用相同幂等键和请求体。使用新键可能创建另一个付费任务；同键不同参数会返回 409。
在有效期内使用 quoteId 按报价提交，也可用 maxCostCredits 拒绝超过预算的任务。文件链接会过期，重新调用结果接口即可刷新，不需要重复处理。
错误处理
“错误处理”章节| 状态码 | 建议 |
|---|---|
| 401 / 403 | 检查密钥、有效期、撤销状态和权限 |
| 402 | 检查账户积分余额 |
| 409 | 阅读 detail，检查参数、报价或任务状态冲突 |
| 410 | 请求的结果或任务已不可用 |
| 422 | 按契约修正请求字段 |
| 429 | 遵守 Retry-After，降低请求并发 |
| 503 | 当前处理能力或依赖服务暂不可用 |
准确的请求和响应字段见当前部署版本的在线 API 参考。接口参考与这里的静态使用指南分别提供。