视频通用说明

用 OpenAI 兼容的 Videos 接口调用可灵视频：提交任务、查询进度、下载视频，以及各型号参数与计费。

流程

视频生成是异步任务，分三步：

POST /v1/videos 提交任务，拿到任务 id。
GET /v1/videos/{id} 轮询进度，直到 status 为 completed 或 failed。
GET /v1/videos/{id}/content 下载 MP4。

一条视频通常需要 1–5 分钟。建议每 10–15 秒查询一次，不要高频轮询。

所有请求都使用 Authorization: Bearer YOUR_API_KEY 认证。

提交任务

POST https://modelrouter.club/v1/videos

字段	类型	必填	说明
`model`	string	是	模型 ID，例如 `kling-3.0`
`prompt`	string	文生视频必填	画面与运动描述
`seconds`	integer	否	时长（秒），默认 5，范围见下表
`resolution`	string	否	`720P` 或 `1080P`，默认 `720P`
`aspect_ratio`	string	否	`16:9`、`9:16`、`1:1`；只对文生视频生效
`size`	string	否	也可用 `1280x720` 这类尺寸代替 `resolution` + `aspect_ratio`
`audio`	boolean	否	是否同步生成音频，默认 `false`；仅部分型号支持
`input_reference`	string / array	图生视频必填	首帧图片 URL；传两张时，第一张为首帧，第二张为尾帧
`negative_prompt`	string	否	不希望出现的内容
`seed`	integer	否	随机种子

注意

首帧、尾帧只接受公网可访问的 http(s) 图片 URL，不支持上传文件或 Base64。图生视频的画面比例跟随首帧图片，此时 aspect_ratio 不生效。

各型号参数

模型 ID	时长	分辨率	有声
`kling-3.0`	3–15 秒	720P / 1080P	支持
`kling-3.0-omni`	3–15 秒	720P / 1080P	支持
`kling-2.6`	3–15 秒	720P / 1080P	仅 1080P 支持
`kling-3.0-turbo`	3–15 秒	720P / 1080P	不支持
`kling-o1`	3–15 秒	720P / 1080P	不支持
`kling-2.5`	5 或 10 秒	720P / 1080P	不支持

所有型号都支持文生视频，以及首帧 / 首尾帧图生视频。

示例：文生视频

curl https://modelrouter.club/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "prompt": "清晨的海边，一只柯基在沙滩上奔跑，镜头缓慢跟随",
    "seconds": 5,
    "resolution": "720P",
    "aspect_ratio": "16:9"
  }'

示例：首尾帧图生视频

curl https://modelrouter.club/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "prompt": "花朵从含苞到完全绽放",
    "seconds": 5,
    "input_reference": [
      "https://example.com/first.jpg",
      "https://example.com/last.jpg"
    ]
  }'

提交成功后返回任务对象（示例结构）：

{
  "id": "task_xxxxxxxx",
  "object": "video",
  "status": "queued",
  "progress": 0
}

查询进度

GET https://modelrouter.club/v1/videos/{id}

curl https://modelrouter.club/v1/videos/task_xxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "task_xxxxxxxx",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "seconds": "5"
}

`status`	含义
`queued`	排队中
`in_progress`	生成中；`progress` 为 0–100 的进度
`completed`	已完成，可以下载
`failed`	失败；`error.message` 给出原因，费用自动退回

失败时的响应示例：

{
  "id": "task_xxxxxxxx",
  "object": "video",
  "status": "failed",
  "progress": 100,
  "error": { "code": "task_failed", "message": "..." }
}

下载视频

GET https://modelrouter.club/v1/videos/{id}/content

curl -L https://modelrouter.club/v1/videos/task_xxxxxxxx/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o video.mp4

返回 MP4 文件内容。

注意

视频约 7 天内可以下载。过期后接口返回 410，错误码为 artifact_gone，无法再取回。请在任务完成后及时下载，转存到自己的存储。

计费

按秒计费，按分辨率和是否有声分档，费用为「单价 × 时长」。
提交任务时按请求的时长、分辨率预扣费用；任务失败后自动全额退回。
各型号的实时单价见模型广场，更多说明见价格说明。

常见错误

错误信息	原因
`prompt or input_reference is required`	既没有 `prompt`，也没有首帧图片
`seconds must be an integer between 3 and 15`	时长超出范围
`seconds must be one of 5, 10`	`kling-2.5` 只支持 5 秒或 10 秒
`resolution must be one of 720P, 1080P`	分辨率不支持
`aspect_ratio must be one of ...`	比例不支持
`this model does not generate audio`	该型号不支持有声
`audio requires 1080P for this model`	`kling-2.6` 有声需要 1080P
`at most two images are supported ...`	图片超过两张（首帧 + 尾帧）
`input_reference must be an HTTP(S) URL ...`	图片不是 URL，或传了文件 / Base64

其他错误见排错指南。

目录