常见问题
常见问题与解答
排查 API Key、模型权限、任务等待、下载和扣费问题。
调用报错
调用失败时先读取 HTTP 状态码，再保存响应体中的错误信息和请求时间。不要记录完整 API Key 或包含 敏感数据的请求正文。
| 状态码 | 含义 | 建议处理 |
|---|---|---|
400 | 请求字段或格式不正确 | 检查 JSON、模型名、消息或 parameters 层级；修正后再提交 |
401 | API Key 缺失、失效或被停用 | 检查 Bearer Header 和控制台令牌状态 |
403 | 当前请求无权访问 | 核对 Key 的模型范围；参见下方模型权限问题 |
402 | 可用额度不足 | 查看余额、令牌额度和控制台消费日志 |
404 | 路径、Operation、Artifact 或模型不存在 | 对照对应 API 文档，并使用公开模型全名 |
429 | 请求过多或当前资源受限 | 降低并发；响应包含 Retry-After 时按其等待 |
5xx | 平台或上游暂时失败 | 保存错误信息；先确认原请求状态，再决定是否重试 |
推荐重试边界
400、401、402、404需要修改请求或账号状态，不应原样循环重试；429、503只有在错误明确允许重试时才有限重试，并遵守Retry-After；- 创建任务失败或超时时，保留原请求及幂等键；查询任务可以继续查询原 ID；
- 同一个应用应设置总超时、最大重试次数和并发上限；
- 如果无法确认上一次请求是否已经完成，不要无限并发补发相同业务操作。
长耗时任务还应遵守任务与结果文件中的幂等、轮询和
recovery_required 处理规则。
模型可见但调用失败
先查询这把 Key 的模型目录，确认请求中的模型 ID 完整且正确。若返回 403，检查
API 密钥页面的模型范围；仍无法调用时，请联系支持核对账号分组。
目录可见不等于调用已成功，模型暂不可用时也可能拒绝请求。
任务一直在等待
queued 表示排队，running 表示执行中；继续查询原任务，按 Retry-After 等待。
客户端等待超时不等于服务端任务失败，不要换幂等键重复提交。任务等待与恢复。
下载的是 JSON，为什么不能播放
提交任务返回的是状态 JSON。成功后需要下载结果文件，语音模型返回 MP3 或 WAV，图片模型返回 PNG； ASR 的识别结果本身就是 JSON。下载结果文件。
为什么余额足够却无法提交
除账号余额外，Key 本身也可能有额度限制。ASR 提交时还会预扣最长音频对应的金额，完成后结算并退回差额。 请查看价格与计费和使用日志。
联系支持
当前支持入口为管理员微信 zxdwhda_01。请提供请求时间、模型名、HTTP 状态码和脱敏后的错误信息。
涉及任务时可附任务 ID，不要发送完整 API Key 或敏感请求正文。