模型路由 视频生成模型

一、概述

POST /v1/videos — 创建视频生成任务GET /v1/videos/{video_id} — 查询单个任务GET /v1/videos — 查询任务列表DELETE /v1/videos/{video_id} — 取消任务

二、前提条件

1. 建议提前阅读 使用约束 与 支持的模型提供商 了解相关信息。

2. 已创建模型路由实例，详细操作指导请参见 创建模型路由实例。

3. 已创建 BYOK 实例，详细操作指导请参见 创建 BYOK 实例。

4. 已创建模型路由访问密钥（API Key），详细操作指导请参见 创建模型路由访问密钥。

5. 已完成视频生成模型关联和模型路由策略配置，详细操作指导请参见 配置模型调度管理。

四、请求地址

POST {CMR_BASE_URL}/v1/videosGET {CMR_BASE_URL}/v1/videos/{video_id}GET {CMR_BASE_URL}/v1/videosDELETE {CMR_BASE_URL}/v1/videos/{video_id}

CMR_BASE_URL 为控制台展示的实例访问地址。请求使用 CMR 模型名称和 CMR API Key，无需填写厂商的接口地址或 API Key。

五、请求头

六、快速开始

将示例中的访问地址、API Key 和模型名称替换为自己的配置。

七、cURL

# ① 创建任务curl –request POST "${CMR_BASE_URL}/v1/videos" \\ –header "Authorization: Bearer ${CMR_API_KEY}" \\ –header "Content-Type: application/json" \\ –data '{ "model": "kling-v3", "contents": [ { "type": "text", "text": "一只橙色小猫在窗台上看向镜头，阳光洒在毛发上" } ], "duration": 5, "resolution": "1080p", "aspect_ratio": "16:9" }'# → {"id":"video_abc123","error":null}# ② 轮询任务状态，直到 status 为 completed 或 failedcurl –request GET "${CMR_BASE_URL}/v1/videos/video_abc123" \\ –header "Authorization: Bearer ${CMR_API_KEY}"# ③ status=completed 后，从 outputs[0].url 获取视频并尽快下载转存

八、Python

import osimport timeimport requestsbase_url = os.environ["CMR_BASE_URL"]headers = { "Authorization": f"Bearer {os.environ['CMR_API_KEY']}", "Content-Type": "application/json",}# ① 创建任务resp = requests.post( f"{base_url}/v1/videos", headers=headers, json={ "model": "kling-v3", "contents": [ {"type": "text", "text": "一只橙色小猫在窗台上看向镜头，阳光洒在毛发上"} ], "duration": 5, "resolution": "1080p", "aspect_ratio": "16:9", }, timeout=30,)resp.raise_for_status()video_id = resp.json()["id"]# ② 轮询任务状态（建议间隔 5 秒以上）while True: task = requests.get( f"{base_url}/v1/videos/{video_id}", headers=headers, timeout=30, ).json() if task["status"] in ("completed", "failed", "expired"): break time.sleep(5)# ③ 获取结果if task["status"] == "completed": print(task["outputs"][0]["url"]) # 视频地址，请尽快下载转存else: print(task["error"])

九、创建任务

POST /v1/videos

十、请求参数

参数取值与模型能力：duration、resolution、aspect_ratio 等参数的取值是否被所选模型支持，由模型侧校验——传入了模型不支持的取值时，请求会返回相应错误（错误信息来自模型侧，便于排查）。选填参数是否生效取决于所选模型，未填写的选填参数 CMR 不自动补默认值。

十一、素材结构

contents 数组中每项为一个素材对象：

素材与任务类型的匹配：

格式约束：图片支持 jpg/jpeg/png/webp，大小 ≤50MB，短边 ≥300px；视频支持 mp4/mov，时长限制以所选模型为准。first_frame+last_frame 与 reference 类素材不可混用；base 与 feature 视频不可混用。

十二、请求示例

图生视频（指定首帧）：

{ "model": "kling-v3", "contents": [ { "type": "text", "text": "让画面中的主体自然转头，微风吹动头发" }, { "type": "image", "role": "first_frame", "url": "https://example.com/start.jpg" } ], "duration": 5, "resolution": "1080p", "aspect_ratio": "16:9"}

视频生视频：

{ "model": "kling-3.0-omni", "contents": [ { "type": "text", "text": "让画面主体自然转头" }, { "type": "video", "role": "feature", "url": "https://example.com/clip.mp4" } ]}

十三、响应参数

十四、响应示例

{ "id": "video_abc123", "error": null}

创建接口为异步受理：返回 id 只表示任务已受理排队，不代表生成成功，请通过查询接口获取最终结果。

十五、Provider 自定义参数

CMR 实例默认开启参数转换，并默认透传厂商自定义参数。按厂商要求将参数放入请求即可，无需逐个配置放行；如果实例已配置参数过滤规则，则按该规则处理。

例如，所选模型支持 return_last_frame（返回尾帧图，用于多段视频接力）时，可以这样请求：

{ "model": "doubao-seedance-2-5", "contents": [{ "type": "text", "text": "清晨的咖啡馆里，一杯咖啡冒着热气" }], "return_last_frame": true}

如需设置默认值、修改参数值或过滤字段，可在目标 CMR 实例的参数转换配置中设置规则。通过管理 API 配置时，使用 CreateParamTranslationConfig 保存、TestParamTranslationConfig 预览；Video 规则的端点填写 video。配置方法和示例可参考参数协议转换说明。自定义参数的名称、填写层级和取值以厂商说明为准。更换模型或厂商后，请确认这些参数仍然适用。

十六、查询任务

GET /v1/videos/{video_id}

路径参数 video_id 为创建时返回的任务 ID。

十七、响应参数

基本字段：

任务失败：查询接口本身失败（如任务不存在、无权限）返回统一错误格式；任务生成失败是任务属性而非请求失败——查询仍返回 HTTP 200，失败原因在 error 字段中。

产物 outputs[]（当前每个任务返回一个视频）：

用量 usage（终态返回；进行中为 null）：

CMR 只返回模型实际提供的用量字段内容，缺失项为 null 而非补 0。

十八、响应示例

{ "id": "video_abc123", "object": "video", "status": "completed", "created_at": 1787000000, "completed_at": 1787000300, "model": "kling-v3", "error": null, "outputs": [ { "url": "https://example-cdn.com/output/abc123.mp4?sign=…", "cover_url": "https://example-cdn.com/output/abc123_cover.jpg?sign=…", "watermark_url": null, "last_frame_url": null } ], "usage": { "seconds": 5, "width": 1920, "height": 1080, "fps": 24, "tokens": null, "billing": null }}

十九、查询任务列表

GET /v1/videos

20、请求参数

21、响应参数

offset + limit < total 时还有下一页，由调用方自行判断。列表仅返回当前 CMR API Key 所属实例的任务。

22、取消任务

DELETE /v1/videos/{video_id}

仅 queued（排队中）状态的任务可取消。取消成功返回 204 No Content（无响应体）。

取消成功后，任务进入 failed 终态，error.code 为 cancelled。

是否支持取消取决于所选模型对应的厂商：不支持时返回 405（cancel_not_supported）；任务已开始生成或已终态时返回 409（conflict）。

23、任务状态

状态只会向前迁移，不会回退；终态（completed/failed/expired）不再变化。建议轮询间隔 5 秒以上，避免高频查询。

24、结果地址说明

·outputs[].url 为模型侧的临时下载地址，各厂商有效期不同（最短约 12 小时），请在任务完成后尽快下载转存。

·地址过期后访问会失败，且 CMR 不提供重新获取地址的能力。

·需要精确过期时间的调用方，可自行解析地址中的签名参数（如 URL 中的 Expires、q-sign-time 等字段，以实际返回为准）。

25、错误响应

·请求失败时，CMR 返回统一的错误格式：

{ "error": { "message": "duration 7 超出模型支持范围", "type": "invalid_request_error", "param": "duration", "code": "invalid_parameter" }}

·常见错误码