使用指南
错误处理与排查
常见 API、模型和参考素材问题的处理方式
面向平台用户的操作步骤与创作流程说明
错误处理与排查
常见 HTTP 状态
| 状态 | 常见原因 | 处理建议 |
|---|---|---|
| 400 | 模型、参数、尺寸、时长或素材不符合要求 | 以返回的字段提示为准，调整请求后重新创建。 |
| 401 | API Key 缺失、无效或已撤销 | 检查 Authorization: Bearer，必要时重新创建 Key。 |
| 403 | 当前 Key 没有模型或资源权限 | 调用 /v1/models 确认可见模型。 |
| 404 | 路径或任务 ID 不存在 | 检查基础地址、API 版本和任务 ID。 |
| 429 | 触发请求限制 | 按响应建议退避，避免并发重复提交。 |
| 500 | 请求处理失败 | 保存请求 ID 和精简后的请求信息，稍后重试或联系支持。 |
| 503 | 当前模型暂无可用服务 | 切换同类模型或稍后重试。 |
视频参考图读取失败
类似 image_url ... resource download failed 的错误，表示模型服务无法读取参考素材，而不是提示词本身的问题。检查顺序如下：
- API 调用：确认参考地址/数据仍有效、格式受支持，并且服务端能够读取。
- LocoPal Creation 素材库引用：确认素材状态为可用；仍在处理或审核时先等待完成。
- 直接上传：重新选择原始图片后提交，不要把浏览器本地路径传给 API。
- 仍失败：换一张合规且可读取的素材，并保留请求 ID 供支持排查。
模型不可用
“No available channel for model” 或“模型暂不可用”表示平台此刻没有可路由的服务，不是简单重试就必然成功。先查询 /v1/models，再换同能力模型；对于生产任务，业务端应向用户展示可恢复状态并保留原始请求，而不是无提示地连续创建新任务。
提交支持请求时提供什么
请提供：发生时间、模型名称、请求 ID、HTTP 状态、脱敏后的错误代码，以及是否为文本/图片/视频请求。不要提交 API Key、完整用户隐私素材、登录 Cookie 或第三方账户信息。
重试前的判断
| 情况 | 是否直接重试 | 建议 |
|---|---|---|
| 本地网络短暂中断，且已有任务 ID | 否 | 先查询原任务。 |
| 参数或素材格式错误 | 否 | 按错误提示修正字段或文件后重新创建。 |
| 模型暂不可用 | 视情况 | 切换当前可用的同类模型，或稍后再试。 |
| 已进入失败终态 | 否 | 保留原错误与请求 ID，修正原因后创建新任务。 |
| LocoPal Creation 原对话中的可重试失败 | 可以 | 使用“直接重试”，在原记录中确认等待状态更新。 |
保护账户与资料
任何排错信息都应先脱敏：隐藏 API Key、Authorization 请求头、Cookie、签名 URL 中的敏感参数和真实人像资料。平台支持人员通常只需要请求 ID、模型、时间、状态码与简化后的错误内容来定位问题。