先判断哪个环节失败
| 环节 | 判断方法 | 下一步 |
|---|---|---|
| 鉴权和提交 | HTTP 非 2xx | 检查 error、请求头、完整模型名和参数 |
| 等待生成 | status 为 queued 或 in_progress | 约每 10 秒查询原 response.id |
| 同步或流式观察超时 | 同步 queued，或 SSE response.incomplete | 继续 GET /v1/responses/{response_id}，不是重新创建 |
| 生成或结果观察失败 | status 为 failed | 检查 error 和 metadata.task_status，再查任务日志 |
| 下载 | completed 后 /content 仍失败 | 检查视频任务 ID、权限、保存期限和服务端结果解析 |
创建、查询和下载都使用 Authorization: Bearer YOUR_API_KEY。Google Key、Google operation name 与青云 API Key、resp_…、task_… 不能混用。
常见错误
| 现象 | 检查与处理 |
|---|---|
| 401 / 403 | Key 是否完整、有效，Bearer 后是否有空格；模型和分组是否允许访问 |
| 400 / model is required | 使用完整 model；可用模型以该 Key 的 GET /v1/models 为准 |
| input must be a string or array | input 使用字符串或消息数组；不要放一个普通对象 |
| input is required | 提供非空文字或一张图片；文字建议放 input |
| input image must be a data URL or base64 value | 图片先编码为 data URL；普通 http/https 图片地址不能使用 |
| metadata must be an object | Responses 使用 JSON 对象，不要传转义后的 JSON 字符串 |
| 图片未生效或选错 | 只提供一种图片来源；本入口只使用优先级最高的第一张图 |
| 高清、时长参数被拒绝 | Veo 3.1 使用 4/6/8 秒；1080p 和 4k 使用 8 秒，分辨率写 metadata.resolution |
| 413 | 图片编码后的请求体过大，压缩素材或改用统一视频接口的 multipart 上传 |
| 429 | 遵循 Retry-After、降低并发和轮询频率 |
| 404 / 响应不存在 | 使用创建返回的 resp_…，同一账号的 Key；不要把 task_… 填入 Responses 查询路径 |
| 5xx / 超时 / 断线 | 查询可保留原 ID 重试；创建未拿到 ID 时先查控制台任务日志 |
| response.failed | error 可能只给通用说明；检查 metadata.task_status 和控制台日志，不要只看 HTTP 200 |
| 下载返回 JSON | 这是错误信息或错误路径；先检查状态码，不要当作视频保存 |
本入口的能力限制
本站 Veo 视频入口为 /v1/responses 和 /v1/videos，本目录不提供 Google 原生 predictLongRunning 或 operation 查询入口。不要把官方示例的域名替换为本站，也不要把 instances、parameters 原样发送给 Responses。
只使用一张起始图片并输出一个视频，不提供多参考图、首尾帧控制、视频延长、视频 remix、批量 n、独立音频开关或帧率设置。Veo 3.1 与 Fast 使用相同请求结构，切换时填写对应的完整模型 ID。
Responses 是本本站支持的视频输入输出格式，不代表视频模型能调用工具或保存聊天上下文。tools、previous_response_id、instructions 等字段不是本入口的视频参数。metadata 被用于 Google 生成选项，任意业务标签可能被上游拒绝。
已完成但视频不可用
如果任务状态为 completed，但下载返回 artifact_not_found 或 Responses 无法返回视频结果，先确认下载路径、任务 ID、账号权限及文件保存期限。任务完成状态不能代替文件下载检查。
仍无法获取视频时，请保留 response.id、metadata.task_id、模型名、提交时间和脱敏错误，联系本站支持。不要通过更换 Key、重写提示词或重复创建来尝试恢复同一任务的结果。
相关文档
联系支持时提供请求路径、HTTP 状态、脱敏错误、模型和两个 ID。不要发送完整 API Key、Authorization 请求头、图片 Base64 或带 access 的临时授权链接。