创建视频生成任务 API

本文介绍创建视频生成任务 API 的输入输出参数，供您使用接口时查阅字段含义。模型会依据传入的图片及文本信息生成视频，待生成完成后，您可以按条件查询任务并获取生成的视频。
模型名称：artsdance-2-5-pro-260801

模型能力

Seedance 2.5（有声视频 / 无声视频）

全模态参考生视频：输入参考图片（0-30 张）+ 参考视频（0-10 个）+ 参考音频（0-10 个）+ 文本提示词（可选）生成 1 个目标视频。支持仅传入音频。支持生成全新视频、编辑视频、延长视频，支持 30 秒视频连贯直出。

图生视频-首尾帧：输入首帧图片 + 尾帧图片 + 文本提示词（可选）生成 1 个目标视频。

图生视频-首帧：输入首帧图片 + 文本提示词（可选）生成 1 个目标视频。

文生视频：输入文本提示词生成 1 个目标视频。

参数传入方式说明

对于 resolution、ratio、duration、frames、seed、camera_fixed、watermark 参数，除了在 request body 中直接传入，也支持在文本提示词后追加 --[parameters] 的弱校验方式传参。

示例

1、文生视频

curl -X POST https://tokenra.io/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "artsdance-2-5-pro-260801",
    "content": [
        {
            "type": "text",
            "text": "写实风格，晴朗的蓝天之下，一大片白色的雏菊花田，镜头逐渐拉近，最终定格在一朵雏菊花的特写上，花瓣上有几颗晶莹的露珠"
        }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "watermark": false
}'

2、多模态参考

curl -X POST https://tokenra.io/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "artsdance-2-5-pro-260801",
    "content": [
        {
            "type": "text",
            "text": "明亮多彩的广告片风格，果味饼干为主角，包含草莓、苹果、葡萄、橙子四种口味，草莓味参考@图像1.."
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://arkdocs.tos-cn-beijing.volces.com/images/video-generation/seedance2.5_reference1.png"
            },
            "role": "reference_image"
        },
        {
            "type": "video_url",
            "video_url": {
                "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference2.mp4"
            },
            "role": "reference_video"
        },
        {
            "type": "video_url",
            "video_url": {
                "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference3.mp4"
            },
            "role": "reference_video"
        },
        {
            "type": "video_url",
            "video_url": {
                "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference4.mp4"
            },
            "role": "reference_video"
        },
        {
            "type": "video_url",
            "video_url": {
                "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference5.mp4"
            },
            "role": "reference_video"
        },
        {
            "type": "video_url",
            "video_url": {
                "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference6.mp4"
            },
            "role": "reference_video"
        },
        {
            "type": "video_url",
            "video_url": {
                "url": "https://arkdocs.tos-cn-beijing.volces.com/videos/video-generation/seedance2.5_reference7.mp4"
            },
            "role": "reference_video"
        }
    ],
    "generate_audio": true,
    "ratio": "16:9",
    "duration": 15
}'

3、有声视频-首帧

curl -X POST https://tokenra.io/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "artsdance-2-5-pro-260801",
    "content": [
        {
            "type": "text",
            "text": "女孩抱着狐狸，女孩睁开眼，温柔地看向镜头，狐狸友善地抱着，镜头缓缓拉出，女孩的头发被风吹动，可以听到风声"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
            }
        }
    ],
    "generate_audio":true,
    "ratio": "adaptive",
    "duration": 5,
    "watermark": false
}'

4、有声视频-首尾帧

curl -X POST https://tokenra.io/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "artsdance-2-5-pro-260801",
    "content": [
        {
            "type": "text",
            "text": "女孩抱着狐狸，女孩睁开眼，温柔地看向镜头，狐狸友善地抱着，镜头缓缓拉出，女孩的头发被风吹动，可以听到风声"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
            }
        }
    ],
    "generate_audio":true,
    "ratio": "adaptive",
    "duration": 5,
    "watermark": false
}'

请求参数

Body 参数

`model` `string` `必选`

模型 ID，填入 artsdance-2-5-pro-260801 。

`content` `object[]` `必选`

输入内容列表，支持以下组合：

纯文本

文本（可选）+ 图片

文本（可选）+ 视频

文本（可选）+ 音频（Seedance 2.5 支持单独传入音频）

文本（可选）+ 图片 + 音频

文本（可选）+ 图片 + 视频

文本（可选）+ 视频 + 音频

文本（可选）+ 图片 + 视频 + 音频

文本信息

字段	类型	必选	说明
`type`	string	✅	固定为 `text`
`text`	string	✅	视频生成提示词

提示词说明：

语言支持：中文、英文、西班牙语、印度尼西亚语、葡萄牙语、日语、马来语、泰语、阿拉伯语、越南语、韩语

字数建议：中文不超过 500 字，英文不超过 1000 词

图片信息

字段	类型	必选	说明
`type`	string	✅	固定为 `image_url`
`image_url.url`	string	✅	图片 URL / Base64 编码 / 素材 ID（`asset://<ASSET_ID>`）
`role`	string	条件必填	图片用途，见下表

role 取值说明：

场景	role 取值	图片数量
图生视频-首帧	`first_frame` 或不填	1 张
图生视频-首尾帧	首帧：`first_frame`；尾帧：`last_frame`	2 张（必填）
全模态参考生视频	`reference_image`	1-30 张

单张图片要求：

格式：jpeg、png、webp、bmp、tiff、gif、heic、heif

宽高比（宽/高）：[0.4, 2.5]

宽高长度（px）：[300, 6000]

大小：单张 < 30 MB，请求体 ≤ 64 MB

注意：图生视频-首帧、图生视频-首尾帧、全模态参考生视频为 3 种互斥场景，不可混用。

视频信息

字段	类型	必选	说明
`type`	string	✅	固定为 `video_url`
`video_url.url`	string	✅	视频 URL / 素材 ID（`asset://<ASSET_ID>`）
`role`	string	—	固定为 `reference_video`

单个视频要求：

格式：mp4、mov（支持 H.264/AVC、H.265/HEVC 编码）

分辨率：480p、720p、1080p、4k

时长：

非视频编辑任务：[2, 30] s

视频编辑任务：[4, 30] s

最多传入 10 个，所有视频总时长 ≤ 30 s

宽高比（宽/高）：[0.4, 2.5]

宽高长度（px）：[300, 6000]

大小：单个 ≤ 200 MB

帧率（FPS）：[24, 60]

音频信息

字段	类型	必选	说明
`type`	string	✅	固定为 `audio_url`
`audio_url.url`	string	✅	音频 URL / Base64 编码 / 素材 ID
`role`	string	—	固定为 `reference_audio`

✅ Seedance 2.5 支持单独传入音频，无需搭配图片/视频。

单个音频要求：

格式：wav、mp3

时长：单个 [2, 30] s，最多 10 段，总时长 ≤ 30 s

大小：单个 ≤ 15 MB，请求体 ≤ 64 MB

`omni_reference_task_type` `string` `默认值 auto`

Seedance 2.5 全模态参考生视频任务类型引导，包含 3 类子任务：

取值	说明	特殊参数限制
`auto`	模型自动判定任务类型	无
`reference`	参考生视频	`ratio` / `duration` 无特殊限制
`edit`	视频编辑	`content` 中必须至少含 1 个 `reference_video`；视频时长 4–30 s；`ratio` 必须为 `adaptive`；`duration` 必须为 `-1`
`extend`	视频延长	`content` 中必须至少含 1 个 `reference_video`；`ratio` 必须为 `adaptive`

`resolution` `string`

视频分辨率。

默认值	可选值
`720p`	`720p`、`1080p`

1080p 视频采用 10bit 位深 + H.265/HEVC 编码，色彩层次更丰富，满足专业影视制作需求。

`ratio` `string`

生成视频的宽高比。

默认值：adaptive

任务类型	ratio 说明
文生视频	支持 `adaptive` 或指定宽高比（`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`）
首帧/首尾帧生视频	仅支持 `adaptive`，自动与首帧图片宽高比保持一致
视频编辑/视频延长	仅支持 `adaptive`，自动与待编辑/延长视频宽高比保持一致
参考生视频	支持 `adaptive` 或指定宽高比

`duration` `integer`

生成视频时长（单位：秒）。

默认值：-1（智能选择）

取值范围：[4, 30]，或 -1（智能选择）

`duration = -1` 规则	说明
视频编辑任务	自动保持与待编辑视频时长基本一致，输出时长可能为非整数秒，误差约 0.4 秒
其他任务类型	模型在有效取值范围内自主选择合适时长（整数秒）

注意**：视频编辑任务仅支持 duration=-1，不支持指定具体时长。

`generate_audio` `boolean` `默认值 true`

控制生成的视频是否包含声音。

true：生成包含同步音频的有声视频（人声 + 音效 + 背景音乐）

false：生成无声视频

生成的有声视频均为单声道，与传入的音频声道数无关。

`output_format` `string` `默认值 mp4`

输出视频格式。

取值	说明	适用场景
`mp4`	通用格式，兼容性最好	网页、移动端、各类播放器及分发平台
`mov`	高色彩精度格式，更好保持色彩与亮度一致性	调色、抠像、合成等专业后期加工

推荐在视频编辑、视频延长场景使用 mov 格式作为输入和输出。

mov 格式兼容播放器：

播放器	macOS	Windows
IINA	✓	✕
VLC	✓	✓
mpv	✓	✓
ffplay	✓	✓

`watermark` `boolean` `默认值 false`

true：生成视频右下角展示 AI 生成 水印

false：不含水印

`return_last_frame` `boolean` `默认值 false`

是否返回生成视频的尾帧图像（png 格式，无水印）。可用于生成多个连续视频：以上一个视频的尾帧作为下一个视频任务的首帧。

`callback_url` `string`

任务结果回调通知地址。当任务状态变化时，方舟将向此地址推送 POST 请求。

回调 status 包括：queued（排队中）、running（运行中）、succeeded（成功）、failed（失败）、expired（超时）

`execution_expires_after` `integer` `默认值 172800`

任务超时阈值（单位：秒），从 created_at 时间戳开始计算，默认 48 小时。

取值范围：[3600, 259200]

`priority` `integer` `默认值 0`

执行优先级，数值越大优先级越高，高优先级请求将插队到同 Endpoint 下低优先级请求之前。

取值范围：[0, 9]

相同优先级按 FIFO 排序

仅影响排队顺序，不中断已运行任务

仅在同一 Endpoint 内生效

`tools` `object[]`

工具配置，支持 type: web_search（联网搜索）。开启后模型根据提示词自主判断是否搜索互联网内容，可提升时效性但会增加时延。

`safety_identifier` `string`

终端用户唯一标识符（英文字符串，长度 ≤ 64），建议传入对用户名/ID/邮箱哈希处理后的字符串。

响应参数

`id` `string`

视频生成任务 ID，仅保存 7 天（从 created_at 时间戳开始计算）。

创建视频生成任务为异步接口，获取 ID 后需通过查询视频生成任务 API 查询任务状态。任务成功后输出生成视频的 video_url。

查询视频生成任务 API

请求参数

Path 参数

参数	类型	必选	说明
`id`	string	✅	您需要查询的视频生成任务 ID

请求示例

curl -X GET "https://tokenra.io/v1/video/generations/$TASK_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY"

响应示例

{
    "id": "cgt-2026****-****",
    "model": "seedance-2-0-fast",
    "status": "succeeded",
    "content": {
        "video_url": "https://ark-content-generation-cn-beijing.tos-cn-beijing.volces.com/xxx"
    },
    "usage": {
        "completion_tokens": 108900,
        "total_tokens": 108900
    },
    "created_at": 1779348818,
    "updated_at": 1779348874,
    "seed": 78674,
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "framespersecond": 24,
    "service_tier": "default",
    "execution_expires_after": 172800,
    "generate_audio": true,
    "draft": false,
    "priority": 0
}

响应参数

任务基本信息

参数	类型	说明
`id`	string	视频生成任务 ID
`model`	string	任务使用的模型名称和版本，格式为 `模型名称-版本`
`status`	string	任务状态，见下表
`created_at`	integer	任务创建时间的 Unix 时间戳（秒）
`updated_at`	integer	任务当前状态更新时间的 Unix 时间戳（秒）
`execution_expires_after`	integer	任务提交后的过期时间（秒），超时未完成将自动终止并标记为 `expired`

status 取值说明：

状态值	说明
`queued`	排队中
`running`	任务运行中
`cancelled`	已取消（仅 `queued` 状态的任务可被取消，取消状态 24h 后自动删除）
`succeeded`	任务成功
`failed`	任务失败

输出内容 `content`

参数	类型	说明
`content.video_url`	string	生成视频的 URL。有效期 24 小时，下载次数上限 100 次，请及时下载或转存
`content.last_frame_url`	string	视频尾帧图像 URL。有效期 24 小时，下载次数上限 100 次。仅在创建任务时设置 `"return_last_frame": true` 时返回

视频参数信息

参数	类型	说明
`resolution`	string	生成视频的分辨率
`ratio`	string	生成视频的宽高比
`duration`	integer	生成视频的时长（秒）。与 `frames` 二选一返回，未指定 `frames` 时返回此字段
`framespersecond`	integer	生成视频的帧率
`generate_audio`	boolean	生成的视频是否包含同步音频：`true` 有声，`false` 无声

其他参数

参数	类型	说明
`seed`	integer	本次请求使用的随机种子值
`service_tier`	string	实际处理任务使用的服务等级
`safety_identifier`	string	终端用户唯一标识符，若创建任务时设置了该参数，接口原样返回

工具使用 `tools`

参数	类型	说明
`tools`	object[]	本次请求模型实际使用的工具，未使用工具时不返回
`tools.type`	string	实际使用的工具类型，目前支持 `web_search`（联网搜索）

Token 用量 `usage`

参数	类型	说明
`usage.completion_tokens`	integer	模型生成视频消耗的 token 数量，可作为计费对账依据
`usage.total_tokens`	integer	本次请求消耗的总 token 数。视频生成模型不统计输入 token，故 `total_tokens` = `completion_tokens`
`usage.tool_usage.web_search`	integer	实际调用联网搜索工具的次数，仅开启联网搜索时返回

错误信息 `error`

任务成功时返回 null，任务失败时返回错误数据。

参数	类型	说明
`error.code`	string	错误码
`error.message`	string	错误提示信息

Seedance 2.5 API接口文档

创建视频生成任务 API#

模型能力#

参数传入方式说明#

示例#

1、文生视频#

2、多模态参考#

3、有声视频-首帧#

4、有声视频-首尾帧#

请求参数#

Body 参数#

model string 必选#

content object[] 必选#

文本信息#

图片信息#

视频信息#

音频信息#

omni_reference_task_type string 默认值 auto#

resolution string#

ratio string#

duration integer#

generate_audio boolean 默认值 true#

output_format string 默认值 mp4#

watermark boolean 默认值 false#

return_last_frame boolean 默认值 false#

callback_url string#

execution_expires_after integer 默认值 172800#

priority integer 默认值 0#

tools object[]#

safety_identifier string#

响应参数#

id string#

查询视频生成任务 API#

请求参数#

Path 参数#

请求示例#

响应示例#

响应参数#

任务基本信息#

输出内容 content#

视频参数信息#

其他参数#

工具使用 tools#

Token 用量 usage#

错误信息 error#

创建视频生成任务 API

模型能力

参数传入方式说明

示例

1、文生视频

2、多模态参考

3、有声视频-首帧

4、有声视频-首尾帧

请求参数

Body 参数

`model` `string` `必选`

`content` `object[]` `必选`

文本信息

图片信息

视频信息

音频信息

`omni_reference_task_type` `string` `默认值 auto`

`resolution` `string`

`ratio` `string`

`duration` `integer`

`generate_audio` `boolean` `默认值 true`

`output_format` `string` `默认值 mp4`

`watermark` `boolean` `默认值 false`

`return_last_frame` `boolean` `默认值 false`

`callback_url` `string`

`execution_expires_after` `integer` `默认值 172800`

`priority` `integer` `默认值 0`

`tools` `object[]`

`safety_identifier` `string`

响应参数

`id` `string`

查询视频生成任务 API

请求参数

Path 参数

请求示例

响应示例

响应参数

任务基本信息

输出内容 `content`

视频参数信息

其他参数

工具使用 `tools`

Token 用量 `usage`

错误信息 `error`