5 分钟接入
拿到密钥，创建任务，再取回视频。
API 是异步的：创建后会先返回任务 ID。每隔 5～10 秒查一次，看到 succeeded 后读取视频链接。
"channel":"channel-1"、"channel":"channel-3" 或 "channel":"channel-4"。不传时使用默认渠道。先跑通一条任务
把示例里的密钥换成你的密钥。开启超分后，平台会自动先生成 480P，再升到目标清晰度。
渠道 3 · Drama / Seedance
渠道 3 同时支持 Drama 和 Seedance 系列模型；negative_prompt 和 seed 是可选的高级参数。
渠道 4 · SD2.5 真人参考
渠道 4 只开放 sd2_5_official_real：支持 480P / 720P、4～30 秒、最多 30 张图片和 10 个音频，不支持视频参考。
查询这条任务
看到 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。
| 参数 | 是否必填 | 怎么填 | 默认值 |
|---|---|---|---|
channel | 选填 | channel-3 / channel-4 | 不传时使用渠道 3 |
model | 必填 | 渠道 1：video-pro 等；渠道 4：sd2_5_official_real | — |
content | 必填 | 非空数组；支持文字、图片、视频、音频 URL | — |
ratio | 选填 | adaptive、16:9、9:16、1:1、4:3、3:4、21:9 | adaptive |
duration | 选填 | -1 自动，或 4～15 秒；Fast 最长 12 秒 | 5 |
super_resolution | 选填 | 内置超分：{"resolution":"1080p"}；腾讯 MPS：{"provider":"tencent_mps","resolution":"2x","type":"hq"} | 不超分 |
resolution | 选填 | 不超分时的原生输出：480p / 720p / 1080p；Mini 不支持原生 1080p | 720p |
generate_audio | 选填 | true 一起生成声音，false 静音 | true |
tools | 选填 | 联网搜索仅支持 [{"type":"web_search"}] | 关闭 |
auto_ingest_images | 选填 | 是否自动保存 HTTPS 图片，布尔值 | false |
超分和原生清晰度二选一：传了 super_resolution 后，平台会自动把 resolution 固定为 480p，你不需要自己处理。
腾讯 MPS 是 2 倍超分：480P 输入通常会得到约 960P 的输出，接口会返回真实宽高；hq 画质优先，lq 速度优先。
渠道 4 参数：ratio 支持 16:9、9:16、21:9、1:1、4:3；duration 支持 4～30 的整数；原生 resolution 支持 480p / 720p，也可选择腾讯 MPS 2 倍超分；不支持 generate_audio 和视频参考。
文字和素材怎么传
本地文件先调用上传接口，再把返回的 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 个，必须搭配图片或视频 |
渠道 4 的素材上限不同：参考图片最多 30 张，参考音频最多 10 个且可以单独使用；参考视频会直接返回参数错误。
首尾帧示例
图片、视频、音频混合参考
返回结果和任务状态
创建成功返回 HTTP 201；相同 Idempotency-Key 重试时返回同一任务，避免重复扣费。
正在产生视频，预占金额尚未最终结算。
已完成，按该渠道的计价规则从余额结算。
失败原因在 error，预占金额会自动退回。
成功结果示例
billing.amount 是本次人民币实付金额；渠道 1 还会在 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 个字符。网络超时后可以安全重试，不会重复创建任务或重复扣费。