说明 - Model API

支持modal

db-s-2-0-260128

db-s-2-0-fast-260128

设计原则

先兼容两个核心接口：

POST /v1/videos

GET /v1/videos/:id

核心接口

1. 创建视频任务

POST /v1/videos

支持的 Content-Type

multipart/form-data

建议优先使用 JSON。

对于 multipart/form-data，第一版仅支持表单字段中传 URL，不支持上传实际文件。

请求字段

字段	类型	必填	说明
`model`	string	是	豆包视频模型名
`prompt`	string	是	提示词。第一版建议必填
`duration`	int	否	视频时长，优先于 `seconds`
`seconds`	int	否	视频时长
`ratio`	string	否	`21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `adaptive`
`resolution`	string	否	`480p` / `720p`
`watermark`	bool	否	是否带水印
`generate_audio`	bool	否	是否生成音频
`input_reference`	string	否	单参考图片 URL，兼容字段
`image`	string	否	单参考图片 URL，兼容字段
`image_url`	string	否	单参考图片 URL，兼容字段
`input_reference_role`	string	否	`first_frame` 或 `reference_image`
`first_frame_url`	string	否	首帧图 URL
`last_frame_url`	string	否	尾帧图 URL
`reference_image_urls`	string[]	否	多张参考图 URL
`reference_video_url`	string	否	单个参考视频 URL
`reference_video_urls`	string[]	否	多个参考视频 URL
`audio_url`	string	否	参考音频 URL
`audio_urls`	string[]	否	多个参考音频 URL
`tools`	array	否	例如 `[{"type":"web_search"}]`
`web_search`	bool	否	`true` 时桥接为 `tools=[{"type":"web_search"}]`
`size`	string	否	OpenAI 兼容尺寸字段，仅支持预设映射

字段映射规则

OpenAI 兼容字段	豆包 native 映射
`model`	`model`
`prompt`	`content += {type:"text", text: prompt}`
`duration` / `seconds`	`duration`
`ratio`	`ratio`
`resolution`	`resolution`
`watermark`	`watermark`
`generate_audio`	`generate_audio`
`first_frame_url`	`content += image_url(role=first_frame)`
`last_frame_url`	`content += image_url(role=last_frame)`
`reference_image_urls[]`	`content += image_url(role=reference_image)`
`reference_video_url(s)`	`content += video_url(role=reference_video)`
`audio_url`	`content += audio_url(role=reference_audio)`
`input_reference` / `image` / `image_url`	默认映射为 `image_url(role=first_frame)`
`input_reference_role=reference_image`	映射为 `image_url(role=reference_image)`
`tools`	`tools`
`web_search=true`	`tools=[{"type":"web_search"}]`

组合规则

audio_url 不能单独出现，至少要和参考图或参考视频一起使用。

input_reference 默认按首帧图处理。

若同时给出 input_reference 和 first_frame_url，以 first_frame_url 为准。

tools 和 web_search 不应同时重复传递；如果都传，优先使用 tools。

`size` 映射规则

由于豆包 native 接口使用 ratio + resolution，桥接层不建议做任意像素近似，仅支持下列固定映射：

`size`	`ratio`	`resolution`
`1280x720`	`16:9`	`720p`
`720x1280`	`9:16`	`720p`
`1024x1024`	`1:1`	`720p`
`832x624`	`4:3`	`720p`
`624x832`	`3:4`	`720p`
`1280x544`	`21:9`	`720p`
`854x480`	`16:9`	`480p`
`480x854`	`9:16`	`480p`
`640x480`	`4:3`	`480p`
`480x640`	`3:4`	`480p`
`480x480`	`1:1`	`480p`

不在映射表中的 size 直接返回 400 invalid_request_error。

adaptive 比例规则
文生视频：根据提示词自动选择最合适的宽高比
首帧 / 首尾帧视频：根据首帧图片选择最接近的宽高比
多模态参考视频：根据提示词意图并以第一个媒体文件为准（优先级：视频 > 图片）选择最接近的宽高比

请求示例

示例 1：最小文生视频

示例 2：首帧图生视频

示例 3：首尾帧视频

示例 4：多模态参考

示例 5：联网搜索增强

示例 6：显式 `tools`

示例 7：使用 `size`

示例 8：multipart 表单

成功响应示例

{
  "object": "video",
  "id": "dbv1_xxxxx",
  "status": "queued",
  "progress": 0,
  "created_at": 1742450000,
  "model": "doubao-seedance-2-0-260128",
  "seconds": "5",
  "size": "1280x720"
}

说明：

id 是桥接层签名任务令牌

下游不需要理解令牌结构，只需原样用于查询

2. 查询视频任务

GET /v1/videos/:id

请求示例

处理中响应示例

{
  "object": "video",
  "id": "dbv1_xxxxx",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1742450000,
  "completed_at": null,
  "model": "doubao-seedance-2-0-260128",
  "seconds": "5",
  "size": "1280x720"
}

完成响应示例

{
  "object": "video",
  "id": "dbv1_xxxxx",
  "status": "completed",
  "progress": 100,
  "created_at": 1742450000,
  "completed_at": 1742450068,
  "model": "doubao-seedance-2-0-260128",
  "seconds": "5",
  "size": "1280x720",
  "url": "https://example.com/output.mp4",
  "video_url": "https://example.com/output.mp4"
}

错误响应格式

统一返回 OpenAI 风格错误：

{
  "error": {
    "message": "error message",
    "type": "invalid_request_error",
    "code": "invalid_size"
  }
}

错误码列表

HTTP 状态码	type	code	说明
`400`	`invalid_request_error`	`invalid_request`	请求格式错误
`400`	`invalid_request_error`	`missing_model`	缺少 `model`
`400`	`invalid_request_error`	`missing_prompt`	缺少 `prompt`
`400`	`invalid_request_error`	`invalid_size`	`size` 不在支持列表
`400`	`invalid_request_error`	`invalid_ratio`	`ratio` 非法
`400`	`invalid_request_error`	`invalid_resolution`	`resolution` 非法
`400`	`invalid_request_error`	`invalid_reference`	参考素材非法
`400`	`invalid_request_error`	`audio_requires_reference`	`audio_url` 缺少图或视频参考
`401`	`authentication_error`	`missing_api_key`	缺少 `Authorization`
`401`	`authentication_error`	`invalid_api_key`	API Key 无效
`403`	`permission_error`	`permission_denied`	无访问权限
`429`	`rate_limit_error`	`rate_limit_exceeded`	上游限流
`500`	`api_error`	`internal_error`	桥接层内部错误
`502`	`api_error`	`upstream_error`	上游返回异常
`504`	`api_error`	`upstream_timeout`	上游超时
`501`	`not_supported_error`	`not_supported`	当前版本不支持的能力

辅助接口

这些接口不是核心兼容 API，但建议提供，方便运维和接入 newapi。

`GET /health`

健康检查。

响应示例：

{
  "status": "ok"
}

`POST /v1/chat/completions`

用于 newapi 渠道测试的占位接口。

建议始终返回一个固定成功响应，不参与真实业务。

图片输入
支持格式：jpeg、png、webp、bmp、tiff、gif
宽高比（宽/高）：
0.4 ~ 2.5
宽高长度：
300 ~ 6000 px
单张图片大小：小于
30 MB
请求体总大小：不超过
64 MB
数量限制：
首帧模式：1 张
首尾帧模式：2 张
多模态参考：1 ~ 9 张

仅支持
video_url
作为参考视频
支持格式：mp4、mov
支持分辨率：
480p
、
720p
单个视频时长：
2 ~ 15 s
最多传入 3 个参考视频，且总时长不超过 15 秒
宽高比（宽/高）：
0.4 ~ 2.5
宽高长度：
300 ~ 6000 px
画面像素范围：
409600 ~ 927408
单个视频大小：不超过
50 MB
帧率：
24 ~ 60 FPS

仅支持
audio_url
作为参考音频
支持格式：wav、mp3
单个音频时长：
2 ~ 15 s
最多传入 3 段参考音频，且总时长不超过 15 秒
单个音频大小：不超过
15 MB

说明

设计原则#

核心接口#

1. 创建视频任务#

支持的 Content-Type#

请求字段#

字段映射规则#

组合规则#

size 映射规则#

请求示例#

示例 1：最小文生视频#

示例 2：首帧图生视频#

示例 3：首尾帧视频#

示例 4：多模态参考#

示例 5：联网搜索增强#

示例 6：显式 tools#

示例 7：使用 size#

示例 8：multipart 表单#

成功响应示例#

2. 查询视频任务#

请求示例#

处理中响应示例#

完成响应示例#

错误响应格式#

错误码列表#

辅助接口#

GET /health#

POST /v1/chat/completions#

设计原则

核心接口

1. 创建视频任务

支持的 Content-Type

请求字段

字段映射规则

组合规则

`size` 映射规则

请求示例

示例 1：最小文生视频

示例 2：首帧图生视频

示例 3：首尾帧视频

示例 4：多模态参考

示例 5：联网搜索增强

示例 6：显式 `tools`

示例 7：使用 `size`

示例 8：multipart 表单

成功响应示例

2. 查询视频任务

请求示例

处理中响应示例

完成响应示例

错误响应格式

错误码列表

辅助接口

`GET /health`

`POST /v1/chat/completions`