OMNI API
密钥、任务 ID、结果视频。
接口保留 Omni 的异步使用方式。提交后每 5-10 秒轮询，看到 completed 即可下载。
先跑通一条文生视频
提示词必须放在 messages 中，seconds 必须是字符串。
查询这条任务
看到 status: "completed" 后，访问 result.file_url 下载。该地址需要同一把客户密钥。
接口一览
所有业务接口都需要 X-API-Key 或 Authorization: Bearer。
| 方法 | 地址 | 用来做什么 |
|---|---|---|
POST | /v1/generate | 创建 Omni 视频任务 |
GET | /v1/tasks/{任务ID} | 查询单条任务和最终结果 |
GET | /v1/tasks/{任务ID}/file | 下载已完成的 MP4 |
GET | /v1/tasks | 分页查询当前客户的任务 |
DELETE | /v1/tasks/{任务ID} | 取消仍在排队的任务 |
POST | /v1/files | 上传图片或源视频，返回私有 upload:// 引用 |
GET | /v1/files | 查询已上传的素材 |
DELETE | /v1/files/{素材ID} | 从素材列表移除；任务已用的素材仍保留历史预览 |
GET | /healthz | 检查服务是否在线，无需密钥 |
查询任务列表
列表支持 page_num、page_size（1～100）、status 和 model 筛选。
创建任务参数
最少需要 model 和 messages。建议始终明确传比例与时长。
| 参数 | 是否必填 | 怎么填 | 默认值 |
|---|---|---|---|
model | 必填 | omni_flash_*、omni_flash_components_* 或 omni_flash_edit_* | - |
messages | 必填 | OpenAI 格式的消息数组；提示词必须在这里 | - |
aspect_ratio | 建议必填 | 16:9 横屏或 9:16 竖屏 | 16:9 |
seconds | 建议必填 | 字符串 "4" / "6" / "8" / "10" | "10" |
input_video | edit 必填 | HTTP(S) URL、upload:// 引用、data URI 或 holo_upload_id | - |
注意：顶层 prompt 会被拒绝；模型名使用下划线；编辑竖屏视频时一定要显式传 9:16。
图片和视频怎么传
本地文件先调用上传接口，再把返回的 data.url 原样放入请求。
上传本地素材
X-File-Kind 支持 image 和 video。返回的 upload:// 引用只对当前客户有效，服务端会自动转换成 base64、公网 URL 或 HOLO 分段上传 ID。
| 类型 | 格式 | 上限 | 其他要求 |
|---|---|---|---|
| 图片 | JPG / PNG / WebP | 默认 20MB | components 和 edit 最多 3 张 |
| 视频 | MP4 / MOV / WebM | 默认 512MB | 生产可通过环境变量提高到 5GB |
保留时间：没有用过的上传素材默认保留 24 小时。一旦被任务引用，原素材会随任务记录保留，便于在任务详情里回看用户当时的输入。最终视频也会另行持久保存到 OSS。
| 模式 | 模型前缀 | 素材位置 | 数量规则 |
|---|---|---|---|
| 文生视频 | omni_flash | 无 | 只传文本 |
| 多图参考 | omni_flash_components | messages.content[].image_url | 1-3 张 |
| 视频编辑 | omni_flash_edit | input_video + 可选参考图 | 1 段视频 + 0-3 张图 |
多图参考示例
视频编辑示例
返回结果和任务状态
创建成功返回 HTTP 202；相同 Idempotency-Key 重试不会重复扣费。
已进入排队，本地余额已预占。
Omni 正在生成或编辑视频。
已完成并结算实际 upstream credits。
失败原因在 error，预占金额自动退回。
成功结果示例
cost_credits 是上游实际 credits；billing.amount 是本地人民币实付金额。
长期保存：平台会把 Omni 的 24 小时结果链接持久保存到本地目录或 OSS。
常见错误
接口错误都会返回 {"success":false,"error":{"code":"...","message":"..."}}。
| HTTP | 错误码 | 怎么处理 |
|---|---|---|
| 400 | BAD_REQUEST | 参数不符合规则，直接看 message 修改 |
| 401 | UNAUTHORIZED | 检查 X-API-Key 或 Bearer 密钥是否完整、有效 |
| 402 | INSUFFICIENT_BALANCE | 人民币余额不足，请联系管理员充值 |
| 404 | NOT_FOUND | 任务不存在，或任务不属于当前客户 |
| 413 | UPLOAD_TOO_LARGE | 文件超过当前类型的大小上限 |
| 429 | RATE_LIMITED | 请求太快，稍等后重试 |
| 502 | UPSTREAM_ERROR | 上游暂时不可用；创建失败会自动退回预占金额 |
| 500 / 502 | UPLOAD_FAILED / OSS_DELETE_FAILED | OSS 暂时不可用，稍后使用同一文件重试 |
建议：每次创建都传一个业务唯一的 Idempotency-Key，最长 128 个字符。网络超时后可以安全重试，不会重复创建任务或重复扣费。