5 分钟接入
拿到密钥，创建任务，再取回视频。
API 是异步的：创建后会先返回任务 ID。每隔 5～10 秒查一次，看到 succeeded 后读取视频链接。
先跑通一条任务
把示例里的密钥换成你的密钥。开启超分后，平台会自动先生成 480P，再升到目标清晰度。
查询这条任务
看到 status: "succeeded" 后，超分前视频在 content.source_video_url，超分后视频在 content.video_url。平台会自动转存到 OSS；storage.persistent 为 true 时表示已完成持久保存。
接口一览
所有业务接口都需要 Authorization: Bearer 你的密钥。
| 方法 | 地址 | 用来做什么 |
|---|---|---|
POST | /v1/videos/generations/tasks | 创建视频任务 |
GET | /v1/videos/generations/tasks/{任务ID} | 查询单条任务和最终结果 |
GET | /v1/videos/generations/tasks | 分页查询当前密钥所属客户的任务 |
POST | /v1/files | 上传素材；图片和视频会自动登记到上游素材库 |
GET | /v1/files | 查询已上传的素材 |
DELETE | /v1/files/{素材ID} | 从素材列表移除；任务已用的素材仍保留历史预览 |
GET | /healthz | 检查服务是否在线，无需密钥 |
查询任务列表
列表支持 page_num、page_size（1～100）、status 和 model 筛选。
创建任务参数
页面上能设置的能力，API 都可以传。只写提示词时，最少传 model 和 content。
| 参数 | 是否必填 | 怎么填 | 默认值 |
|---|---|---|---|
model | 必填 | sora-vip3-pro-720p | — |
content | 必填 | 非空数组；支持文字、图片、视频、音频 URL | — |
ratio | 选填 | 16:9、9:16、1:1、4:3、3:4、21:9 | 16:9 |
duration | 选填 | 5～15 秒 | 5 |
super_resolution | 不支持 | 当前上游没有独立超分接口 | — |
resolution | 选填 | 仅支持原生 720p | 720p |
generate_audio | 选填 | true 一起生成声音，false 静音 | true |
tools | 选填 | 联网搜索仅支持 [{"type":"web_search"}] | 关闭 |
auto_ingest_images | 选填 | 是否自动保存 HTTPS 图片，布尔值 | false |
当前上游限制：只支持 VIP3 Pro 原生 720P；图片、视频和音频必须使用公开可访问的 HTTP(S) URL，不能传 Asset://。
文字和素材怎么传
本地文件先调用上传接口，再把返回的 data.url 原样放进 content。图片和视频会返回 Asset://，页面预览使用 preview_url。
上传本地素材
X-File-Kind 可传 image、video 或 audio；X-File-Name 传带扩展名的文件名。图片和视频会等到上游素材状态为 active 后才返回成功。涉及真人的参考素材必须使用返回的 Asset://，但仍需遵守上游审核规则。
| 类型 | 格式 | 上限 | 其他要求 |
|---|---|---|---|
| 图片 | JPG / PNG / WebP / BMP / TIFF / GIF | 30MB | 300-6000px，宽高比 0.4-2.5 |
| 视频 | MP4 / MOV | 50MB | 2-15 秒，480P / 720P，24-60 FPS |
| 音频 | MP3 / WAV | 15MB | 2-15 秒 |
保留时间：没有用过的上传素材默认保留 24 小时。一旦被任务引用，原素材会随任务记录保留，便于在任务详情里回看用户当时的输入。最终视频也会另行持久保存到 OSS。
| 素材 | content.type | role | 数量规则 |
|---|---|---|---|
| 文字 | text | 不用传 | 内容不能为空，最多 10,000 字符 |
| 首帧 / 尾帧 | image_url | first_frame / last_frame | 各 1 张；尾帧必须搭配首帧 |
| 参考图片 | image_url | reference_image | 最多 9 张，不能与首尾帧混用 |
| 参考视频 | video_url | reference_video | 最多 3 个 |
| 参考音频 | audio_url | reference_audio | 最多 3 个，必须搭配图片或视频 |
首尾帧示例
图片、视频、音频混合参考
返回结果和任务状态
创建成功返回 HTTP 201；相同 Idempotency-Key 重试时返回同一任务，避免重复扣费。
正在产生视频，预占金额尚未最终结算。
已完成，按实际 Token 从余额扣费。
失败原因在 error，预占金额会自动退回。
成功结果示例
billing.amount 是本次人民币实付金额；usage.total_tokens 是生成和超分合计用量。
需要长期链接时：任务成功后继续查询，直到 storage.persistent 为 true。此时 content.video_url 已经是 OSS 地址。
常见错误
接口错误都会返回 {"success":false,"error":{"code":"...","message":"..."}}。
| HTTP | 错误码 | 怎么处理 |
|---|---|---|
| 400 | BAD_REQUEST | 参数不符合规则，直接看 message 修改 |
| 401 | UNAUTHORIZED | 检查 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 个字符。网络超时后可以安全重试，不会重复创建任务或重复扣费。