视频生成接口
提交异步视频生成任务、查询任务状态并获取生成内容。
视频生成是异步接口。提交接口只负责受理任务并返回公开任务对象；生成过程、供应商轮询和最终结算在后台完成。
提交任务
以下三个路径行为相同：
POST /v1/videosPOST /v1/videos/generationsPOST /v1/video/generations
请求使用 application/json 和 Authorization: Bearer <API_KEY>。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | 建议显式指定目录中的视频模型；未提供时网关使用内置默认值，实际以模型目录为准。 |
prompt | string | 条件 | 文生视频必填；带 media 时可选。 |
negative_prompt | string | 否 | 反向提示词。 |
media | array | 否 | 图生、首尾帧、视频续写或编辑素材。 |
image | string | 否 | media 的首帧兼容别名。 |
duration | integer | 否 | 视频时长，单位秒。也可使用 seconds。 |
resolution | string | 否 | 如 1920x1080 或 1080P。也可使用 size。 |
ratio | string | 否 | 如 16:9、9:16、1:1、4:3 或 3:4。 |
fps | integer | 否 | 帧率。 |
audio_url | string | 否 | 驱动音频 URL。 |
reference_voice | string | 否 | 参考音频 URL。 |
audio_setting | string | 否 | 视频编辑声音设置，如 auto 或 origin。 |
seed | integer | 否 | 随机种子。 |
response_format | string | 否 | url 或 b64_json，是否支持取决于模型。 |
user | string | 否 | 终端用户标识。 |
media[].type 支持 first_frame、last_frame、driving_audio 和 first_clip。media[].url 可使用公网 URL、对象存储临时 URL 或 base64 data URL。模型要求素材时，缺少必填素材会在任务预扣前返回 400。
请求示例
curl "${BASE_URL}/v1/videos" \
-H "Authorization: Bearer ${APIQIK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "<video-model-id>",
"prompt": "镜头缓慢推进一片晨雾中的竹林",
"duration": 5,
"resolution": "1920x1080",
"ratio": "16:9"
}'提交响应
{
"id": "video_01JEXAMPLE",
"object": "video",
"model": "<video-model-id>",
"status": "queued",
"progress": 0,
"created_at": 1789987200,
"seconds": 5,
"size": "1920x1080"
}公开 id 只用于网关查询，不应依赖其内部格式。提交失败时不会返回可查询的成功任务。
模型选择
模型目录中 capabilities 含 video 的条目即可用于本接口。文生视频、图生视频、参考图生视频、视频编辑等具体能力，以及时长、分辨率档位和计费口径，以控制台的模型详情为准，本文档不列举固定清单。
调用 GET /v1/public/models?availableOnly=true 可查看当前可用的视频模型。
查询任务
GET/v1/videos/{video_id}
响应仍为 object: "video"。常见状态包括 queued、processing、completed 和 failed；处理中使用 progress 表示进度，完成后可能包含 completed_at 和 url，失败时包含：
{
"id": "video_01JEXAMPLE",
"object": "video",
"status": "failed",
"progress": 0,
"error": {
"code": "upstream_error",
"message": "video generation failed"
}
}客户端应按退避策略轮询，不要高频请求未完成任务。任务终态由后台任务系统推进，查询接口不是结算接口。
获取内容
GET/v1/videos/{video_id}/content
成功时重定向到生成结果 URL。客户端应跟随 302，并按重定向后的响应下载内容；任务未完成、失败或结果不可用时返回结构化错误。
计费和重试
视频提交会在受理阶段进行余额预扣，后台根据供应商任务终态结算或释放。提交响应未到达客户端时，不要盲目重复创建任务；先使用业务侧保存的 X-Request-Id 和任务信息排查。