文档目录

视频(四种格式)

通用 / Sora / 可灵 / 即梦四种入站格式的字段与信封、厂商原生路径、七态到四态的映射。

内容最后核对:2026-11-18

本页目录

四种入站格式,同一个任务、同一个 id。路由由 model 决定,与走哪个入口无关。

格式入口契约来源
通用/v1/video/generations本网关定义
Sora/v1/videosOpenAI 官方
可灵/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
remixPOST /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}查询
MiniMaxPOST /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可灵即梦
QUEUEDqueuedqueuedsubmittedin_queue
RUNNING / CREATEDin_progressin_progressprocessinggenerating
VERIFIEDcompletedcompletedsucceeddone
LINK_EXPIREDfailedfailedfailedexpired
FAILED / SUBMIT_FAILED / EXPIRED / CANCELEDfailedfailedfailedcode:50500
  • 终态:VERIFIED、LINK_EXPIRED、FAILED、SUBMIT_FAILED、EXPIRED、CANCELED。
  • 未知值一律当「还在跑」,不按失败处理:把一次网络抖动当成失败会让你重提,那是第二笔钱。
  • VERIFIED 之后链接仍会被复查,所以它可能转成 LINK_EXPIRED。状态没变不代表链接一定能下。
  • 四个格式的 failed 把七种原因压成一种;要精确原因看控制台任务详情里的 failCode / failDetail,或 Sora 形状的 state。