FAQ 与排错

浏览器 Playground 报 CORS 错误怎么办？

第一版 Playground 使用浏览器直连网关，不经过文档站代理。你需要在 API 网关允许文档站域名跨域访问，并允许以下请求头：

• Authorization
• Content-Type
• 业务侧需要的其他自定义头

为什么返回 model_not_allowed？

当前 API Key 没有目标模型权限。请在 APIKey 管理中检查模型范围，或使用管理开放 API 更新模型白名单。

为什么返回 insufficient_balance？

平台会在模型调用前进行余额预检。余额不足时会拒绝请求，避免上游调用后无法扣费。

视频生成为什么没有立刻返回下载地址？

视频生成通常是异步任务。提交接口返回任务 ID 后，请轮询 GET /v1/videos/generations/{taskId} 查询最终状态。

管理 token 和模型调用 API Key 可以混用吗？

不建议混用。模型调用 API Key 用于 /v1/chat/completions 等模型接口；管理 token 用于 APIKey 管理、余额、账单、充值等开放管理接口。

文档和代码不一致时以谁为准？

第一版文档以当前后端实现为主口径，docs/openapi.yaml 和产品说明书作为补充校准源。若出现差异，请优先以后端 Controller、请求 / 响应 DTO、网关路由与当前实际返回为准。