提交外部视频模型任务

通过晨羽智云应用接口提交外部视频模型任务

POST /api/open/v2/model-runs/videos

提交外部视频模型任务

cURL

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
}
'

200

{
  "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

任务信息

Show data

run_id · string

应用任务 ID。后续查询列表、详情、事件和取消均使用该 ID

gateway_task_id · string

大模型网关任务 ID

model · string

模型 ID

provider · string

供应商标识

status · string

任务状态：created、queued、running、completed、failed、cancelled

settlement_status · string

结算状态：pending、settled、released

frozen_amount · string

预扣金额

代码示例

Python

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"
  }
}