Skip to main content
POST
/
api
/
open
/
v2
/
model-runs
/
videos
提交外部视频模型任务
curl --request POST \
  --url https://www.chenyu.cn/api/open/v2/model-runs/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotency_key": "<string>",
  "request_id": "<string>",
  "inputs": {},
  "inputs.model": "<string>",
  "inputs.prompt": "<string>",
  "inputs.generation_category": "<string>",
  "inputs.first_frame": {},
  "inputs.last_frame": {},
  "inputs.images": [
    {}
  ],
  "inputs.videos": [
    {}
  ],
  "inputs.audios": [
    {}
  ],
  "inputs.duration": 123,
  "inputs.resolution": "<string>",
  "inputs.ratio": "<string>",
  "inputs.contains_real_person_material": true
}
'
{
  "code": 123,
  "msg": "<string>",
  "data": {
    "run_id": "<string>",
    "gateway_task_id": "<string>",
    "model": "<string>",
    "provider": "<string>",
    "status": "<string>",
    "settlement_status": "<string>",
    "frozen_amount": "<string>"
  }
}

​
提交外部视频模型任务

通过 cpn-ai 应用接口提交外部视频模型任务。平台会先完成 API Key 认证和余额预扣，再把任务提交到大模型网关执行。任务完成后按真实结果结算，失败或取消会释放预扣。
idempotency_key 必填。相同 API Key 和相同幂等键的重复请求会返回同一笔任务，避免网络重试造成重复提交和重复预扣。
图片、视频、音频等普通媒体字段直接传资源字符串：公网 URL、data:image/<format>;base64,<data> 或 asset://asset_xxx。需要声明素材角色或在提示词中引用素材时，使用 { "uri": "...", "role": "reference_image", "label": "人物A" }。本地文件建议先调用 上传工作流资源，再把返回的 asset_uri 字段值放入 inputs。

​
请求参数

​
idempotency_key
string
required
幂等键，由调用方生成。建议使用业务订单号、请求流水号或 UUID
​
request_id
string
调用方请求 ID。不传时默认使用 idempotency_key
​
inputs
object
required
外部模型输入参数
​
inputs.model
string
required
视频模型 ID。可通过大模型网关模型列表查询支持视频的模型
​
inputs.prompt
string
required
视频生成提示词
​
inputs.generation_category
string
生成方式。常用值：text_to_video、first_frame_to_video、first_last_frame_to_video
​
inputs.first_frame
object
首帧图片。图生视频或首尾帧视频必填。支持资源字符串，也支持 { "uri": "...", "role": "first_frame", "label": "首帧" }
​
inputs.last_frame
object
尾帧图片。首尾帧视频必填。支持资源字符串，也支持 { "uri": "...", "role": "last_frame", "label": "尾帧" }
​
inputs.images
array
参考图片列表。数组元素支持公网 URL、data URL、asset://asset_xxx，也支持带 uri、role 和 label 的对象。传 label 后可在 inputs.prompt 中用 @label 引用该素材
​
inputs.videos
array
参考视频列表。对象写法支持 uri、role 和 label
​
inputs.audios
array
参考音频列表。对象写法支持 uri、role 和 label
​
inputs.duration
integer
视频时长，单位秒
​
inputs.resolution
string
输出分辨率，例如 480p、720p、1080p。具体支持范围以模型为准
​
inputs.ratio
string
画面比例，例如 16:9、9:16、1:1
​
inputs.contains_real_person_material
boolean
输入图片或视频素材包含真人并需要进行素材备案时传 true

​
响应参数

​
code
integer
响应码，0 表示成功
​
msg
string
响应信息
​
data
object
任务信息

​
代码示例

import uuid
import requests

url = "https://www.chenyu.cn/api/open/v2/model-runs/videos"
headers = {
    "Authorization": "Bearer your_api_key",
    "Content-Type": "application/json"
}
payload = {
    "idempotency_key": str(uuid.uuid4()),
    "inputs": {
        "model": "doubao-seedance-2-0-260128",
        "generation_category": "first_frame_to_video",
        "prompt": "闪白转场，女主在茶园悠闲采茶",
        "first_frame": "asset://asset_first_frame",
        "duration": 5,
        "resolution": "720p",
        "ratio": "16:9",
        "contains_real_person_material": True
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json()["data"]["run_id"])

​
提示词引用素材

多模态参考生视频时，推荐给每个需要被提示词点名的素材设置 label。label 不需要带 @，提示词中引用时再写 @label。 
{
  "idempotency_key": "video_20260613_ref_001",
  "inputs": {
    "model": "doubao-seedance-2-0-fast-260128",
    "generation_category": "reference_to_video",
    "prompt": "@阿九 携手 @沈渡 跳舞",
    "images": [
      {
        "uri": "asset://asset_a252553f9364ad0fa635cb7c48793491",
        "label": "阿九",
        "role": "reference_image"
      },
      {
        "uri": "asset://asset_cf7584e3e836a2b3ee65ef072a71fdd6",
        "label": "沈渡",
        "role": "reference_image"
      }
    ],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9"
  }
}
说明：
  • label 会被服务端去掉首尾空格和可选的 @ 前缀，建议直接写 阿九
  • prompt 中支持 @阿九，也兼容 {{阿九}} 和 {{ 阿九 }}
  • 同一个请求里 label 不能重复
  • 服务端会把自定义标签绑定到当前请求中的资源顺序，例如图片会映射为上游需要的 @图1、@图2

​
响应示例

{
  "code": 0,
  "msg": "提交成功",
  "data": {
    "run_id": "modelrun_1782000000000000000_ab12cd34",
    "request_id": "video_20260613_001",
    "endpoint": "videos",
    "model": "doubao-seedance-2-0-260128",
    "provider": "volc",
    "gateway_task_id": "vid_1782000000000000000_ef56ab78",
    "status": "queued",
    "settlement_status": "pending",
    "frozen_amount": "0.60000000"
  }
}