主题模式

火山方舟 视频生成 API 文档 ​

即梦视频生成 ​

即梦视频生成 3.0 Pro 具备多镜头叙事能力，能更精准遵循指令，动态表现流畅自然，支持生成1080P 高清且具专业级质感的视频。

支持功能：

  • 文生视频：输入文本提示词，生成视频；
  • 图生视频-首帧：输入首帧图片和文本提示词，生成视频。

支持的模型 ​

模型名称类型说明
即梦视频生成 3.0 Pro文生视频 / 图生视频即梦视频 3.0 Pro，支持文生视频与图生视频（首帧）

统一请求地址 ​

操作请求方法请求地址
创建任务POST{base_url}/videos
查询任务GET{base_url}/videos/{task_id}

请求头 ​

字段值描述
Content-Typeapplication/json数据交换格式
AuthorizationBearer鉴权信息

创建任务 ​

请求体参数 ​

参数名类型必填说明取值范围/格式
modelstring是模型名称即梦视频生成 3.0 Pro 等（以配置为准）
promptstring文生视频必填文本提示词，描述要生成的视频内容建议 400 字以内，不超过 800 字
img_urlstring图生视频必填*首帧图片 URL有效可访问的图片 URL
image_urlstring图生视频必填*同 img_url，二选一有效可访问的图片 URL
binary_data_base64string / array图生视频必填*首帧图片 Base64 编码与 img_url/image_url 二选一
secondsinteger否视频时长（秒）5、10，默认 5
durationinteger否同 seconds，二选一5、10
framesinteger否总帧数，直接传入时优先于 seconds121（5s）、241（10s）
aspect_ratiostring否视频宽高比（文生视频生效）16:9、4:3、1:1、3:4、9:16、21:9，默认 16:9
sizestring否视频尺寸，会转换为 aspect_ratio如 1920*1080、1920x1080
seedinteger否随机种子，相同值可复现效果默认 -1（随机）
providerobject否服务商偏好，如指定 {"sort": ["火山方舟"]}可选

* 图生视频：prompt 与图片（img_url / image_url / binary_data_base64）二选一必填。

图片要求（图生视频） ​

要求说明
格式JPEG、PNG
数量仅 1 张
大小最大 4.7MB
分辨率最大 4096×4096，最短边 ≥ 320
宽高比长边/短边 ≤ 3

建议图片宽高比接近 aspect_ratio 可选取值，避免裁剪影响效果。

aspect_ratio 与生成尺寸 ​

宽高比生成尺寸
16:91920×1088
4:31664×1248
1:11440×1440
3:41248×1664
9:161088×1920
21:92176×928

请求示例 ​

1. 文生视频 ​

json
{
  "model": "即梦视频生成 3.0 Pro",
  "prompt": "千军万马，草原上骑兵奔腾",
  "aspect_ratio": "16:9",
  "seconds": 5
}

2. 图生视频（图片 URL） ​

json
{
  "model": "即梦视频生成 3.0 Pro",
  "prompt": "画面中的人物开始行走",
  "img_url": "https://example.com/first-frame.jpg",
  "seconds": 5
}

3. 图生视频（Base64） ​

json
{
  "model": "即梦视频生成 3.0 Pro",
  "prompt": "画面中的人物开始行走",
  "binary_data_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
  "seconds": 10
}

响应格式 ​

创建任务响应（POST /videos） ​

json
{
  "id": "7392616336519610409_abc123",
  "status": "queued",
  "created_at": "2025-02-12T10:00:00.000000Z",
  "model": "即梦视频生成 3.0 Pro",
  "seconds": 5,
  "size": "1920*1088"
}
字段类型说明
idstring任务 ID，用于 GET /videos/{task*id} 查询；格式为 {原始任务ID}*{模型ID}
statusstring初始为 queued，表示已提交排队
created_atstring任务创建时间（ISO 8601）
modelstring模型名称
secondsinteger视频时长（秒）
sizestring视频尺寸（如 1920*1088）

任务结果需通过 GET /videos/{task_id} 轮询获取。

查询任务 ​

网络协议请求地址请求方法响应格式
https{base_url}/videos/{task_id}GETapplication/json

请求路径参数 ​

参数名类型必填说明
task_idstring是创建任务时返回的 id

Query 参数（可选） ​

参数名类型必填说明
providerstring否服务商名称（如 火山方舟）。任务不在本地缓存时指定可加快查询

响应体（任务进行中） ​

json
{
  "id": "7392616336519610409_abc123",
  "status": "in_progress",
  "created_at": "2025-02-12T10:00:00.000000Z"
}

响应体（任务完成） ​

json
{
  "id": "7392616336519610409_abc123",
  "status": "completed",
  "created_at": "2025-02-12T10:00:00.000000Z",
  "completed_at": "2025-02-12T10:03:00.000000Z",
  "video_url": "https://xxx/video.mp4",
  "usage": {
    "seconds": 5.0,
    "video_count": 1,
    "size": "1920*1088"
  },
  "raw_response": { ... }
}

响应体（任务失败） ​

json
{
  "id": "7392616336519610409_abc123",
  "status": "failed",
  "created_at": "2025-02-12T10:00:00.000000Z",
  "error": "内容审核未通过"
}

响应字段说明 ​

字段类型说明
idstring任务 ID
statusstring任务状态：queued、in_progress、completed、failed
created_atstring任务创建时间
completed_atstring任务完成时间（仅完成时返回）
video_urlstring生成的视频 URL（仅完成时返回，有效期 1 小时）
usage.secondsfloat视频时长（秒）
usage.video_countint生成的视频数量
usage.sizestring视频尺寸
raw_responseobject火山引擎原始响应（可选）
errorstring错误信息（仅失败时返回）

任务状态 ​

状态说明
queued任务排队中
in_progress任务处理中
completed任务完成
failed任务失败

注意事项 ​

  1. 异步任务：创建任务后返回 id，需轮询 GET /videos/{task_id} 获取结果。
  2. 视频有效期：video_url 有效期为 1 小时，请及时下载或转存。
  3. 任务过期：任务过期时间为 12 小时，超时需重新创建。
  4. prompt 长度：建议 400 字以内，不超过 800 字。

底层接入火山引擎即梦视频 API，官方文档可参考：