视频(四种格式)
通用 / Sora / 可灵 / 即梦四种入站格式的字段与信封、厂商原生路径、七态到四态的映射。
内容最后核对:2026-11-18
本页目录
四种入站格式,同一个任务、同一个 id。路由由 model 决定,与走哪个入口无关。
| 格式 | 入口 | 契约来源 |
|---|---|---|
| 通用 | /v1/video/generations | 本网关定义 |
| Sora | /v1/videos | OpenAI 官方 |
| 可灵 | /kling/v1/videos/* | 可灵官方 |
| 即梦 | /jimeng* | 即梦官方 |
同一任务在四个入口都能查到,字段名不同。七个状态与四种格式的对照见本文末尾的「任务状态」。
POST /v1/video/generations(通用)
| 字段 | 说明 |
|---|---|
model | 必填 |
prompt | 文生视频必填;图生视频可以只给 image |
image | 首帧图,URL 或 data: URI |
duration / seconds | 秒 |
width / height | 像素。网关翻译成 size、resolution、aspect_ratio 三个标准键 |
size / resolution / aspect_ratio | 直接给也行,优先级高于宽高推算 |
seed / fps | 原样透传给认它的上游 |
metadata / params | 其余上游参数,冲突时顶层赢 |
提交 → {"task_id": "579", "status": "queued"}
查询 → {"task_id": "579", "status": "completed", "url": "...", "format": "mp4",
"metadata": {"duration": 5, "width": 1280, "height": 720}}
metadata.duration 是实际产出时长(结算依据),width/height 是请求值 —— 上游不回报实际值,编一个出来会让按它对账的人算错。
明确 400:n > 1(一个任务只产出一个产物)、response_format: "b64_json"。
POST /v1/videos(Sora / OpenAI 官方形状)
唯一有官方 SDK 的格式,字段与 OpenAI 完全一致:id 是字符串、status 四态小写、时间是秒级整数、seconds 是字符串。
| 动作 | 路径 |
|---|---|
| 提交 | POST /v1/videos |
| 查状态 | GET /v1/videos/{id} |
| 下载字节 | GET /v1/videos/{id}/content(variant=video,缩略图 400) |
| 取链接 | GET /v1/videos/{id}/link |
| remix | POST /v1/videos/{id}/remix(请求体只要 prompt) |
| 续期 | POST /v1/videos/{id}/refresh-url |
| 取消 / 删除 | DELETE /v1/videos/{id} → {} |
{"id": "579", "object": "video", "status": "queued", "progress": 0,
"created_at": 1763098879, "seconds": "5", "size": "1280x720",
"state": "QUEUED", "expires_at": 1763185279, "url": null}
state是网关七态原文:SDK 只读status,而排查「为什么失败」需要LINK_EXPIRED/SUBMIT_FAILED这种精确区分。两个字段各有各的读者。/content是字节代理,不是 302:网关替你拉一次,你的出口 IP 不会出现在上游日志里。要热链自己管就用/link。remix把源任务产物当作参考视频(走+VIDEO_IN计价档),是新的一单,不是重跑原任务;源任务必须VERIFIED。
提交失败是 502,响应体仍是 Video 对象、仍带 id(任务已经创建,用它去对账使用日志里关联的 job-<id>),预扣全额退回。
POST /kling/v1/videos/text2video / image2video(可灵)
请求 → {"model_name": "...", "prompt": "...", "image": "https://...", "duration": "5"}
响应 → {"code": 0, "message": "", "request_id": "",
"data": {"task_id": "579", "task_status": "submitted"}}
model_name必填(也接受model);image2video必须给image。duration是字符串("5"/"10")。callback_url、external_task_id一律 400:本站主动查询上游进度,回调没有落点。- 查询:
GET /kling/v1/videos/{text2video|image2video}/{task_id}(两个动作都能查同一任务),data.task_result.videos[].url取产物,时间字段是毫秒。 - 错误码是数值:
1000鉴权、1201参数、1203任务不存在、1302限流、5000服务端错误。
POST /jimeng?Action=...(即梦)
模型版本写在 req_key 里(它同时决定价格档位),没有 model 字段。
| 动作 | 路径 |
|---|---|
| 提交 | POST /jimeng/?Action=CVSync2AsyncSubmitTask 或 POST /jimeng/api/common/v3/submit_task_v2 |
| 查询 | POST /jimeng/?Action=CVSync2AsyncGetResult 或 POST /jimeng/api/common/v3/get_result_v2 |
提交 → {"code": 10000, "data": {"task_id": "579"}, "message": "Success", "status": 10000}
查询 → {"code": 10000, "data": {"status": "done", "video_url": "..."}, ...}
三处照厂商契约来、与我们其它端点不同的地方:
- 成功码是 10000,不是 0、也不是「HTTP 200 即成功」;
- 查不到任务是
code:10000 + data.status:"not_found"(不是 404) —— 回 404 会让调用方当成服务故障去重试; - 任务失败是
code != 10000(不是data.status:"failed") —— 后者会被只读code的客户端当成「还在跑」。
其它细节:
image_urls的顺序有语义:[0]首帧、[1]尾帧。frames只接受121(5 秒)或241(10 秒),网关同时推出duration(计价读秒)。- 查询时带
req_json会 400:它带查询期设置,而网关回答的是上次轮询的结果。
厂商原生路径(视频)
| 厂商 | 路径 | 说明 |
|---|---|---|
| 火山方舟 | POST /api/v3/contents/generations/tasks | 提交 |
GET /api/v3/contents/generations/tasks/{id} | 查询 | |
DELETE /api/v3/contents/generations/tasks/{id} | 取消 | |
| 阿里百炼 | POST /api/v1/services/aigc/video-generation/video-synthesis | 提交 |
GET /api/v1/tasks/{task_id} | 查询 | |
| MiniMax | POST /v2/video_generation | 提交(旧路径 /v1/video_generation 也认) |
GET /v2/query/video_generation?task_id= | 查询 | |
GET /v1/files/retrieve?file_id= | 取文件 |
有些 SDK 会把 base 里的 /v1 吃掉(火山 Java SDK 用 scheme / host / port 三段重建 URL),于是真实请求没有 /v1。这类形状也接受同一组端点:直接写 /api/v3/contents/generations/tasks 也通。
任务状态
网关用这七个状态描述任务,四种格式各用自己的词表达。判断能否停止轮询看是否终态:
| 网关状态 | 通用 | Sora | 可灵 | 即梦 |
|---|---|---|---|---|
QUEUED | queued | queued | submitted | in_queue |
RUNNING / CREATED | in_progress | in_progress | processing | generating |
VERIFIED | completed | completed | succeed | done |
LINK_EXPIRED | failed | failed | failed | expired |
FAILED / SUBMIT_FAILED / EXPIRED / CANCELED | failed | failed | failed | code:50500 |
- 终态:
VERIFIED、LINK_EXPIRED、FAILED、SUBMIT_FAILED、EXPIRED、CANCELED。 - 未知值一律当「还在跑」,不按失败处理:把一次网络抖动当成失败会让你重提,那是第二笔钱。
VERIFIED之后链接仍会被复查,所以它可能转成LINK_EXPIRED。状态没变不代表链接一定能下。- 四个格式的
failed把七种原因压成一种;要精确原因看控制台任务详情里的failCode/failDetail,或 Sora 形状的state。