02 创建任务 — 完整参数

所有创建任务用的 endpoint 和参数体, 包括边界值和示例。

Endpoint

协议风格	URL
OpenAI 风格 (推荐)	`POST /v1/videos`
Volcengine 风格	`POST /api/v3/contents/generations/tasks`

两个 URL 参数体完全一致;创建任务返回 OpenAI 风格的 OpenAIVideo 对象,Volcengine 风格的 {id} 单字段。查询响应字段差异详见 03 查询任务。本文以 OpenAI 风格为主。

旧路径 POST /v1/video/generations 仍然兼容,但推荐用 POST /v1/videos(跟 OpenAI 官方 Videos API 路径一致)。

请求 Headers

http

POST /v1/videos HTTP/1.1
Host: www.dianlitoken.com
Authorization: Bearer sk-xxxxxxxxxxxx
Content-Type: application/json

请求 Body 结构

json

{
  "model": "seedance-2.0-pro",
  "content": [...],
  "resolution": "720p",
  "duration": 5,
  "ratio": "16:9",
  "generate_audio": false,
  "watermark": false,
  "return_last_frame": false,
  "seed": 12345,
  "callback_url": "https://your-server.com/webhook/seedance"
}

字段详解

`model` (必填, string)

取值	用途	备注
`seedance-2.0-pro`	文生视频 (Pro 高质量)	支持 480p / 720p / 1080p
`seedance-2.0-pro-v2v`	视频参考生成 (Pro)	必须传 `video_url`
`seedance-2.0-fast`	文生视频 (Fast 经济)	不支持 1080p
`seedance-2.0-fast-v2v`	视频参考生成 (Fast)	不支持 1080p

当你传基础模型 (seedance-2.0-pro / seedance-2.0-fast) 而 content 里有 video_url 时, 网关会自动升级到 -v2v 版本, 不用手动改。

`content` (必填, array)

数组里至少 1 个元素, 每个元素是 ContentItem 结构。

ContentItem 字段

字段	类型	用途
`type`	string	`"text"` / `"image_url"` / `"video_url"` / `"audio_url"`
`text`	string	仅 `type=text`
`image_url`	`{url: string}`	仅 `type=image_url`
`video_url`	`{url: string}`	仅 `type=video_url`
`audio_url`	`{url: string}`	仅 `type=audio_url`
`role`	string	`"first_frame"` / `"last_frame"` / `"reference_image"` / `"reference_video"` / `"reference_audio"`

文生视频 (text2video)

只放 text:

json

{
  "model": "seedance-2.0-pro",
  "content": [
    {"type": "text", "text": "一只穿着红色毛衣的橘猫在雪地上跳舞"}
  ]
}

图片转视频 (image2video)

text + 一张图片(图片会被当作首帧):

json

{
  "model": "seedance-2.0-pro",
  "content": [
    {"type": "text", "text": "图中的猫开始奔跑"},
    {
      "type": "image_url",
      "image_url": {"url": "https://example.com/cat.jpg"},
      "role": "first_frame"
    }
  ]
}

图片必须是公网可访问的 URL, 大小建议 < 10MB, JPG/PNG/WEBP 均支持。

视频参考生成 (v2v)

text + 一段参考视频, 模型会模仿视频的风格 / 动作:

json

{
  "model": "seedance-2.0-pro-v2v",
  "content": [
    {"type": "text", "text": "把视频中的人替换成熊猫"},
    {
      "type": "video_url",
      "video_url": {"url": "https://example.com/reference.mp4"},
      "role": "reference_video"
    }
  ]
}

使用 v2v 模型时, 必须包含至少一个 video_url, 否则返回 400。

`resolution` (选填, string, 默认 `"720p"`)

取值	像素	Pro 模型	Fast 模型
`480p`	854×480	✅	✅
`720p`	1280×720	✅	✅
`1080p`	1920×1080	✅	❌

请求 1080p + Fast 模型会返回:

json

{
  "error": {
    "code": "invalid_request",
    "message": "seedance-2.0-fast does not support 1080p resolution"
  }
}

`duration` (选填, int, 默认 `5`)

取值	含义
4-15 (整数)	视频时长(秒)
`-1`	让模型自选最佳时长

预扣费规则:

传 -1 → 按 15 秒预扣
传 4-15 → 按传入值预扣
任务完成后按实际时长重新结算

`ratio` (选填, string)

视频宽高比, 默认由模型决定。

取值	适合场景
`16:9`	横屏 (YouTube, Bilibili)
`9:16`	竖屏 (抖音, Reels, Shorts)
`1:1`	方形 (Instagram)
`4:3`	老电视
`3:4`	复古竖屏
`21:9`	电影感横屏
`adaptive`	自适应 (由模型选择)

`generate_audio` (选填, bool, 默认 `false`)

是否生成配音。开启会按音轨长度增加一些费用。

json

{
  "model": "seedance-2.0-pro",
  "content": [{"type": "text", "text": "..."}],
  "generate_audio": true
}

`watermark` (选填, bool, 默认 `false`)

是否在视频右下角加水印 (官方水印)。通常你不希望开。

`return_last_frame` (选填, bool, 默认 `false`)

如果为 true, 任务完成时除了视频, 还会返回末帧静态图 URL。用于做连续视频(把末帧作为下一段的首帧)。

`seed` (选填, int64)

种子值, 用于复现生成。同样 prompt + 同样 seed → 视频几乎一样。

不传则随机。

`callback_url` (选填, string)

任务完成后, 平台会 POST 任务对象到这个 URL。详见 04 回调。

响应 Body

成功创建后立即返回 (任务还没真正开始跑)。 两个路由返回结构不一样:

OpenAI 风格 `/v1/videos`

json

{
  "id": "cgt-20260527165600-kf7rt",
  "task_id": "cgt-20260527165600-kf7rt",
  "object": "video",
  "model": "seedance-2.0-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1779869660
}

Volcengine 风格 `/api/v3/contents/generations/tasks`

跟官方 spec 一致, 只返一个字段:

json

{
  "id": "cgt-20260527165600-kf7rt"
}

字段说明

字段	何时存在	说明
`id`	两路由总是	任务 ID, 格式 `cgt-yyyymmddhhmmss-xxxxx`(跟 Volcengine 官方一致)
`task_id`	仅 OpenAI 路由	`id` 的别名 (deprecated)
`object`	仅 OpenAI 路由	固定 `"video"`
`model`	仅 OpenAI 路由	客户端传的 model 值
`status`	仅 OpenAI 路由	创建后立即返时总是 `queued`
`progress`	仅 OpenAI 路由	此时总是 `0`
`created_at`	仅 OpenAI 路由	Unix 时间戳

任务 ID 跟上游一致

你拿到的 cgt-yyyymmddhhmmss-xxxxx 是上游 Volcengine 的真实任务 ID, 回调 payload 里的 data.id 跟它完全一致, 不再需要做映射。查询接口、回调通知、内部对账都用同一个 id 就行。

查询任务时拿视频 URL, 见 03 查询任务 — OpenAI 路由在 metadata.url, Volcengine 路由在 content.video_url。创建接口的响应里不会带视频 URL。

错误响应

模型名错误 (400)

json

{
  "error": {
    "code": "invalid_request",
    "message": "unknown model: seedance-3.0"
  }
}

content 为空 (400)

json

{
  "error": {
    "code": "invalid_request",
    "message": "content is required and must contain at least one item"
  }
}

v2v 模型缺 video_url (400)

json

{
  "error": {
    "code": "invalid_request",
    "message": "v2v models require at least one video_url content item"
  }
}

余额不足 (402)

json

{
  "error": {
    "code": "insufficient_quota",
    "message": "Pre-consume quota exceeds available balance. Required: X, Available: Y"
  }
}

内容审核失败 (400, 上游)

json

{
  "error": {
    "code": "upstream_rejected",
    "message": "prompt contains restricted content"
  }
}

完整错误码见 08 错误码。

边界与最佳实践

长 prompt 会被截断吗?

上游官方 prompt 通常上限 1500 字符。建议控制在 500 字内, 描述清晰胜过堆叠词。

多 image_url / video_url 怎么用?

支持多个 image_url(作为不同的参考帧), 但只能有一个 role: "first_frame"。

URL 必须公网可访问

image_url / video_url 必须是公网可访问的 HTTPS 链接。如果是私有存储, 请用 05 素材库上传后用 asset://... 引用。

何时该用 Fast vs Pro?

场景	推荐
测试 / 原型	Fast (便宜 ~3-5 倍)
480p / 720p 短视频	Fast
1080p 长视频 / 商业内容	Pro
需要严格的物体一致性	Pro

下一篇: 03 查询任务 →

02 创建任务 — 完整参数 ​

Endpoint ​

请求 Headers ​

请求 Body 结构 ​

字段详解 ​

model (必填, string) ​

content (必填, array) ​

ContentItem 字段 ​

文生视频 (text2video) ​

图片转视频 (image2video) ​

视频参考生成 (v2v) ​

resolution (选填, string, 默认 "720p") ​

duration (选填, int, 默认 5) ​

ratio (选填, string) ​

generate_audio (选填, bool, 默认 false) ​

watermark (选填, bool, 默认 false) ​

return_last_frame (选填, bool, 默认 false) ​

seed (选填, int64) ​

callback_url (选填, string) ​

响应 Body ​

OpenAI 风格 /v1/videos ​

Volcengine 风格 /api/v3/contents/generations/tasks ​

字段说明 ​

错误响应 ​

模型名错误 (400) ​

content 为空 (400) ​

v2v 模型缺 video_url (400) ​

余额不足 (402) ​

内容审核失败 (400, 上游) ​

边界与最佳实践 ​

长 prompt 会被截断吗? ​

多 image_url / video_url 怎么用? ​

URL 必须公网可访问 ​

何时该用 Fast vs Pro? ​

02 创建任务 — 完整参数

Endpoint

请求 Headers

请求 Body 结构

字段详解

`model` (必填, string)

`content` (必填, array)

ContentItem 字段

文生视频 (text2video)

图片转视频 (image2video)

视频参考生成 (v2v)

`resolution` (选填, string, 默认 `"720p"`)

`duration` (选填, int, 默认 `5`)

`ratio` (选填, string)

`generate_audio` (选填, bool, 默认 `false`)

`watermark` (选填, bool, 默认 `false`)

`return_last_frame` (选填, bool, 默认 `false`)

`seed` (选填, int64)

`callback_url` (选填, string)

响应 Body

OpenAI 风格 `/v1/videos`

Volcengine 风格 `/api/v3/contents/generations/tasks`

字段说明

错误响应

模型名错误 (400)

content 为空 (400)

v2v 模型缺 video_url (400)

余额不足 (402)

内容审核失败 (400, 上游)

边界与最佳实践

长 prompt 会被截断吗?

多 image_url / video_url 怎么用?

URL 必须公网可访问

何时该用 Fast vs Pro?