对外API接口文档

文档概述
1.1 文档范围
本文档仅包含对外提供的三类接口，明确排除非对外相关内容，确保接口信息的针对性和准确性。
•包含接口：文本接口、图片接口、视频接口
•不包含内容：后台管理说明、主账号/子账号创建流程、渠道配置说明、内部部署说明
1.2 基础信息
1.2.1 基础地址
服务器IP示例：http://115.191.24.134
所有接口统一请求路径：http://115.191.24.134/v1
接入说明：无域名时可直接使用服务器IP访问；未配置SSL证书时使用http://你的服务器IP；后续配置域名和HTTPS后，统一替换基础地址即可。
1.2.2 认证方式
所有接口均需携带以下请求头进行身份认证，Content-Type固定为JSON格式：
http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
1.2.3 可用模型
以下为当前对外推荐使用的模型，请求时需传入对应model值，视频模型支持映射关系：
类型名称映射名
文本 Seed 2.0 doubao-seed-2-0-pro-260215
图片豆包图片 5.0 doubao-seedream-5-0-260128
视频山河1.5pro 山河1.5pro
视频山河2.0 山河2.0
备注：外部项目可直接传入视频模型底层真实名称，无需使用映射别名。
文本接口
2.1 标准聊天补全接口
接口信息
•请求方式：POST
•接口路径：/v1/chat/completions
•接口说明：用于标准聊天补全，适用于普通文本生成、问答、改写、标题生成、脚本生成等场景。
请求参数
请求体为JSON格式，必填参数标记为必填，可选参数标记为可选：
•model：必填，字符串类型，文本模型标识，参考1.2.3节可用模型
•messages：必填，数组类型，聊天消息列表，每个元素包含role（角色，可选值：system/user/assistant）和content（消息内容）
•temperature：可选，数字类型，默认0.8，控制生成文本的随机性，值越高随机性越强
请求示例
示例：使用Seed 2.0生成女装上新标题
bash
curl http://115.191.24.134/v1/chat/completions
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"model": "doubao-seed-2-0-pro-260215",
"messages": [
{ "role": "system", "content": "你是一个短视频文案助手" },
{ "role": "user", "content": "给我写3条女装上新标题" }
],
"temperature": 0.8
}'
响应参数
json
{
"id": "chatcmpl_xxx", // 接口响应ID
"object": "chat.completion", // 响应对象类型
"created": 1773396000, // 响应生成时间戳（秒）
"model": "doubao-seed-2-0-pro-260215", // 使用的模型标识
"choices": [ // 生成结果列表
{
"index": 0, // 结果索引
"message": { // 生成的消息
"role": "assistant", // 角色（助手）
"content": "1. 春日轻盈上新 ..." // 生成的内容
},
"finish_reason": "stop" // 生成结束原因（stop：正常结束）
}
],
"usage": { // 令牌使用情况
"prompt_tokens": 100, // 提示词令牌数
"completion_tokens": 120, // 生成内容令牌数
"total_tokens": 220 // 总令牌数
}
}
2.2 兼容Responses风格接口
接口信息
•请求方式：POST
•接口路径：/v1/responses
•接口说明：用于兼容Responses风格输入，适用于只传单段input的调用场景。
请求参数
•model：必填，字符串类型，文本模型标识，参考1.2.3节可用模型
•input：必填，字符串类型，单段输入内容
请求示例
bash
curl http://115.191.24.134/v1/responses
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"model": "doubao-seed-2-0-pro-260215",
"input": "请输出一条适合母婴用品投流的广告文案"
}'
响应参数
响应格式与/v1/chat/completions接口一致，仅生成对应输入的响应内容。
图片接口
3.1 文生图接口
接口信息
•请求方式：POST
•接口路径：/v1/images/generations
•接口说明：根据输入的提示词生成图片，当前推荐使用模型：doubao-seedream-5-0-260128。
请求参数
•model：必填，字符串类型，图片模型标识，参考1.2.3节可用模型
•prompt：必填，字符串类型，图片生成提示词（描述图片内容、风格等）
•size：可选，字符串类型，图片尺寸，例如1K、2K、4K
•aspect_ratio：可选，字符串类型，图片宽高比，例如1:1、16:9、9:16
•response_format：可选，字符串类型，默认url，指定图片返回格式（仅支持url）
请求示例
bash
curl http://115.191.24.134/v1/images/generations
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"model": "doubao-seedream-5-0-260128",
"prompt": "高级感护肤品海报，银白色背景，商业摄影，极简构图",
"size": "2K",
"aspect_ratio": "1:1",
"response_format": "url"
}'
响应参数
json
{
"created": 1773396000, // 图片生成时间戳（秒）
"data": [ // 生成的图片列表
{
"url": "https://example.com/generated-image.png" // 图片访问URL
}
]
}
视频接口
视频接口为异步任务接口，需先调用创建任务接口获取任务ID，再通过任务ID轮询查询任务状态及结果。
4.1 创建视频生成任务
接口信息
•请求方式：POST
•接口路径：/v1/video/generations
•接口说明：创建视频生成任务，首次调用仅返回任务ID，不直接返回视频地址。
请求参数
•model：必填，字符串类型，视频模型标识，推荐山河1.5pro或山河2.0
•prompt：必填，字符串类型，视频描述（内容、风格、镜头等）
•image_url：可选，字符串类型，首帧图URL
•image_end_url：可选，字符串类型，尾帧图URL，仅image_role=first_last_frames时必填
•duration：可选，数字类型，视频时长（秒），范围1-30，默认5
•ratio：可选，字符串类型，视频宽高比，例如16:9、9:16、1:1，默认adaptive
•image_role：可选，字符串类型，图片作用，支持first_frame（首帧）、last_frame（尾帧）、first_last_frames（首尾帧）
•watermark：可选，布尔类型，是否添加水印，默认true
•camera_fixed：可选，布尔类型，是否固定镜头，默认false
特别说明：当image_role=first_last_frames时，必须同时传入image_url和image_end_url。
请求示例
示例1：使用山河1.5pro生成视频
bash
curl http://115.191.24.134/v1/video/generations
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"model": "山河1.5pro",
"prompt": "海边逆光慢镜头，人物回头微笑，电影质感",
"image_url": "https://example.com/first-frame.jpg",
"duration": 5,
"ratio": "16:9",
"watermark": true
}'
示例2：使用山河2.0生成视频
bash
curl http://115.191.24.134/v1/video/generations
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"model": "山河2.0",
"prompt": "城市夜景中人物走向镜头，氛围感强，镜头推进",
"image_url": "https://example.com/start.jpg",
"duration": 5,
"ratio": "9:16",
"watermark": true
}'
示例3：使用首尾帧模式生成视频
bash
curl http://115.191.24.134/v1/video/generations
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"model": "山河2.0",
"prompt": "人物从静止过渡到转身奔跑，镜头自然衔接",
"image_role": "first_last_frames",
"image_url": "https://example.com/first.jpg",
"image_end_url": "https://example.com/last.jpg",
"duration": 5,
"ratio": "16:9"
}'
响应参数
json
{
"success": true, // 任务创建是否成功
"data": {
"provider_task_id": "vgtask_xxx", // 视频任务ID（用于轮询查询）
"raw": {
"id": "vgtask_xxx" // 原始任务ID
}
}
}
4.2 轮询查询视频任务状态
接口信息
•请求方式：GET
•接口路径：/v1/video/generations/:taskId（:taskId替换为创建任务返回的provider_task_id）
•接口说明：用于查询视频生成任务的状态，当状态为success时，可通过result_url获取视频地址。
请求示例
bash
curl http://115.191.24.134/v1/video/generations/vgtask_xxx
-H "Authorization: Bearer YOUR_API_KEY"
响应参数
json
{
"id": "vgtask_xxx", // 任务ID
"object": "video.generation.task", // 响应对象类型
"model": "山河2.0", // 使用的视频模型
"status": "running", // 任务状态（pending/running/success/failed）
"raw_status": "processing", // 原始状态
"result_url": null, // 视频地址（状态为success时非空）
"created": 1773396000000, // 任务创建时间戳（毫秒）
"raw": {
"id": "vgtask_xxx",
"status": "processing"
}
}
任务状态说明
•pending：任务已提交，等待处理
•running：任务正在生成中
•success：任务生成成功，可通过result_url获取视频
•failed：任务生成失败，需重新提交任务
轮询建议
•轮询频率：每5秒轮询一次
•成功处理：轮询到success状态后，读取result_url获取视频
•失败处理：返回failed状态时，结束轮询并记录错误信息
调用示例（JavaScript）
5.1 文本接口调用示例
javascript
const BASE_URL = 'http://115.191.24.134';
const API_KEY = 'YOUR_API_KEY';
async function chatDemo() {
const resp = await fetch(${BASE_URL}/v1/chat/completions, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': Bearer ${API_KEY}
},
body: JSON.stringify({
model: 'doubao-seed-2-0-pro-260215',
messages: [
{ role: 'user', content: '给我写3条女装短视频开场文案' }
]
})
});
return await resp.json();
}
5.2 图片接口调用示例
javascript
const BASE_URL = 'http://115.191.24.134';
const API_KEY = 'YOUR_API_KEY';
async function imageDemo() {
const resp = await fetch(${BASE_URL}/v1/images/generations, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': Bearer ${API_KEY}
},
body: JSON.stringify({
model: 'doubao-seedream-5-0-260128',
prompt: '高级感护肤品海报，银白色背景，商业摄影',
size: '2K',
aspect_ratio: '1:1',
response_format: 'url'
})
});
return await resp.json();
}

4.2.1 创建视频生成任务（Creat）

接口信息

请求方式：POST
接口地址：http://115.191.24.134/v1/video/generations
接口说明：山河2.0专属创建任务接口，支持多模态输入组合，返回任务ID用于后续查询。

核心请求参数

参数名	类型	必填/可选	说明
model	string	必选	固定为`山河2.0`
content	object[]	必选	生成视频的输入信息，支持多模态组合，详见下方多模态说明
service_tier	string	可选	暂不支持，无需传入
generate_audio	boolean	可选	默认true，控制视频是否包含同步声音，false为无声视频
draft	boolean	可选	暂不支持，无需传入
tools	object[]	可选	仅支持`web_search`联网搜索工具，详见下方说明
resolution	string	可选	默认720p，取值：480p/720p
ratio	string	可选	默认adaptive，取值：16:9/4:3/1:1/3:4/9:16/21:9/adaptive
duration	integer	可选	默认5，取值[4,15]或-1（模型智能选择），单位秒
frames	integer	可选	暂不支持，无需传入
camera_fixed	boolean	可选	暂不支持，无需传入
watermark	boolean	可选	默认true，是否添加水印

多模态content参数说明

content为数组类型，支持文本、图片、音频、视频的任意组合（音频不可单独传入），每个元素为对应类型的信息对象，核心类型及参数如下：

1. 文本信息对象

{
  "type": "text", // 必选，固定为text
  "text": "描述期望生成的视频，中文≤500字，英文≤1000词" // 必选，提示词
}

2. 图片信息对象

{
  "type": "image_url", // 必选，固定为image_url
  "image_url": {
    "url": "图片URL/Base64编码/素材ID" // 必选，格式见下方说明
  },
  "role": "first_frame/last_frame/reference_image" // 条件必填，图片用途
}

url格式要求：
- URL：公网可访问图片地址；
- Base64：data:image/<格式>;base64,<编码>，格式小写（png/jpeg等）；
- 素材ID：asset://<ASSET_ID>。
图片基础要求：格式jpeg/png/webp等，宽高比(0.4,2.5)，像素(300,6000)，单张<30MB；
role取值规则：
- 首帧生视频：1张图，role为first_frame或不填；
- 首尾帧生视频：2张图，首帧first_frame、尾帧last_frame（均必填）；
- 参考图生视频：1~9张图，均为reference_image（必填）。

首帧/首尾帧/参考图为互斥场景，不可混用。

3. 视频信息对象

仅山河2.0支持，type固定为video_url：

{
  "type": "video_url", // 必选
  "video_url": {
    "url": "视频URL/素材ID" // 必选，素材ID格式asset://<ASSET_ID>
  },
  "role": "reference_video" // 条件必填，固定为reference_video
}

视频基础要求：格式mp4/mov，分辨率480p/720p，时长[2,15]s，最多传3个，总时长≤15s，单支<50MB，帧率24-60。

4. 音频信息对象

仅山河2.0支持，不可单独传入，需搭配图片/视频，type固定为audio_url：

{
  "type": "audio_url", // 必选
  "audio_url": {
    "url": "音频URL/Base64编码/素材ID" // 必选，Base64格式data:audio/<格式>;base64,<编码>
  },
  "role": "reference_audio" // 条件必填，固定为reference_audio
}

音频基础要求：格式wav/mp3，时长[2,15]s，最多传3个，总时长≤15s，单支<15MB。

tools联网搜索工具参数

仅支持文本生视频，开启后模型可自主搜索互联网内容，增加时延但提升时效性：

{
  "tools": [
    {
      "type": "web_search" // 必选，固定为web_search
    }
  ]
}

分辨率&宽高比像素对照表

分辨率	宽高比	宽高像素值
480p	16:9	864×496
480p	4:3	752×560
480p	1:1	640×640
480p	3:4	560×752
480p	9:16	496×864
480p	21:9	992×432
720p	16:9	1280×720
720p	4:3	1112×834
720p	1:1	960×960
720p	3:4	834×1112
720p	9:16	720×1280
720p	21:9	1470×630

专属接口请求示例

山河2.0 视频接口文档

本文档描述当前网关接口中，山河2.0 视频生成的实际入参规则、限制条件、模式互斥关系，以及网关转发到上游时的结构。

本文档基于当前后端实现导出，适用于当前网关接口：

创建任务：POST /v1/video/generations
查询任务：GET /v1/video/generations/:taskId

1. 接口地址

1.1 创建视频任务

方法：POST
地址：http://115.191.24.134/v1/video/generations
请求头：

{
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_KEY"
}

1.2 查询任务状态

方法：GET
地址：http://115.191.24.134/v1/video/generations/:taskId
请求头：

{
  "Authorization": "Bearer YOUR_API_KEY"
}

2. 当前网关支持的请求格式

当前网关对外支持的是“顶层字段格式”，不是直接接收官方的 content 数组格式。

也就是说，客户端应传：

model
prompt
image_url / image_end_url / image_role
reference_image_urls
reference_video_urls
reference_audio_urls
video_url
audio_url
duration
ratio
watermark
generate_audio
resolution
tools

当前网关会把这些顶层字段解析后，再组装成更接近上游官方要求的 content 多模态结构发送到上游。

注意：

当前网关不建议客户端直接传官方 content 数组作为唯一输入
如果直接传纯 content 数组，而不传顶层 prompt / reference_image_urls 等字段，当前网关不会按预期解析

3. 基础参数

参数	类型	必填	说明
model	string	是	当前使用的山河2.0模型名
prompt	string	是	视频生成提示词
duration	number	否	视频时长，范围 1～30，默认 5
ratio	string	否	宽高比，默认 adaptive
watermark	boolean	否	是否带水印，默认 false
generate_audio	boolean	否	是否生成声音
resolution	string	否	分辨率，如 720p / 480p
tools	array	否	扩展工具参数，如 web_search

4. 三种模式

当前网关按三种场景处理山河2.0视频请求：

首帧 / 尾帧 / 首尾帧模式
多模态参考模式
纯文生模式

这几种模式中，首尾帧类与多模态参考类互斥。

5. 首帧 / 尾帧 / 首尾帧模式

5.1 支持参数

参数	类型	说明
image_url	string	首帧图，可为 URL 或 Base64
image_end_url	string	尾帧图，可为 URL 或 Base64
image_role	string	first_frame / last_frame / first_last_frames

5.2 规则

image_role=first_last_frames 时，必须同时提供 image_url 和 image_end_url
image_role=first_frame 或 last_frame 时，可只传单张图
首尾帧模式不能同时带 reference_image_urls / reference_video_urls / reference_audio_urls / video_url / audio_url

5.3 请求示例

{
  "model": "山河2.0",
  "prompt": "人物从静止过渡到转身奔跑",
  "image_url": "https://example.com/first.jpg",
  "image_end_url": "https://example.com/last.jpg",
  "image_role": "first_last_frames",
  "duration": 5,
  "ratio": "16:9",
  "watermark": false,
  "generate_audio": true,
  "resolution": "720p"
}

6. 多模态参考模式

6.1 支持参数

参数	类型	说明
reference_image_urls	string[]	参考图片数组，支持 URL 或 Base64
reference_video_urls	string[]	参考视频数组，仅支持 http/https URL
reference_audio_urls	string[]	参考音频数组，支持 URL 或 Base64
video_url	string	单个视频参考，支持 http/https URL
audio_url	string	单个音频参考，支持 URL 或 Base64

6.2 数量限制

reference_image_urls 最多 9 张
reference_video_urls 最多 3 个
reference_audio_urls 最多 3 段
如果同时使用 video_url / audio_url，它们也会计入视频 / 音频总数限制

6.3 互斥规则

多模态参考模式不能和以下场景混用：

first_frame
last_frame
first_last_frames

也就是说，如果带了任意参考图 / 参考视频 / 参考音频，就不能再把 image_role 设成 first_frame、last_frame、first_last_frames。

6.4 请求示例

示例 A：1 图 + 1 视频 + 1 音频

{
  "model": "山河2.0",
  "prompt": "根据参考图片、视频和音频生成视频",
  "reference_image_urls": [
    "https://example.com/ref1.png"
  ],
  "reference_video_urls": [
    "https://example.com/ref1.mp4"
  ],
  "reference_audio_urls": [
    "https://example.com/ref1.wav"
  ],
  "duration": 11,
  "ratio": "16:9",
  "watermark": false,
  "generate_audio": true,
  "resolution": "720p"
}

示例 B：2 图 + 2 视频 + 2 音频

{
  "model": "山河2.0",
  "prompt": "根据多组参考素材生成视频",
  "reference_image_urls": [
    "https://example.com/ref1.png",
    "https://example.com/ref2.png"
  ],
  "reference_video_urls": [
    "https://example.com/ref1.mp4",
    "https://example.com/ref2.mp4"
  ],
  "reference_audio_urls": [
    "https://example.com/ref1.wav",
    "https://example.com/ref2.wav"
  ],
  "duration": 11,
  "ratio": "16:9",
  "watermark": false,
  "generate_audio": true,
  "resolution": "720p"
}

7. 纯文生模式

当不带任何图片、视频、音频参考时，接口按纯文生处理。

请求示例

{
  "model": "山河2.0",
  "prompt": "一艘小船行驶在雾气弥漫的江南湖面",
  "duration": 5,
  "ratio": "16:9",
  "watermark": false,
  "generate_audio": true,
  "resolution": "720p"
}

8. 网关转发到上游时的结构

当前网关不是把客户端原始顶层字段原封不动转发给上游，而是会做两层处理：

保留一部分顶层兼容字段
同时组装官方风格的 content 数组

8.1 1 张参考图时

如果仅有 1 张参考图，网关会：

保留 reference_image_urls
额外补一个顶层 image_url
顶层 image_role 设为 reference_image
同时在 content 中放一条 role=reference_image 的 image_url

8.2 多张参考图时

如果参考图大于 1 张，网关会：

保留 reference_image_urls
不再额外补顶层 image_url
在 content 中为每张图都放一条 role=reference_image 的 image_url

8.3 视频和音频参考

对于 reference_video_urls / reference_audio_urls：

顶层字段会保留
content 中也会分别组装为 role=reference_video / role=reference_audio

8.4 是否去重

当前网关不会自动去重。

也就是说：

如果客户端传了两个相同图片 URL，会上送两条相同图片参考
如果客户端传了两个相同视频 URL，会上送两条相同视频参考
如果客户端传了两个相同音频 URL，会上送两条相同音频参考

9. 非法请求示例

9.1 首尾帧与多模态参考混用

{
  "model": "山河2.0",
  "prompt": "错误示例",
  "image_url": "https://example.com/first.jpg",
  "image_end_url": "https://example.com/last.jpg",
  "image_role": "first_last_frames",
  "reference_image_urls": [
    "https://example.com/ref1.png"
  ]
}

这类请求会返回 400，因为首尾帧模式与多模态参考模式互斥。

9.2 超过图片上限

当多模态参考图片总数超过 9 张时，接口会返回 400。

9.3 超过视频上限

当多模态参考视频总数超过 3 个时，接口会返回 400。

9.4 超过音频上限

当多模态参考音频总数超过 3 段时，接口会返回 400。

10. 查询任务状态

创建成功后，接口返回：

{
  "success": true,
  "data": {
    "provider_task_id": "task_xxx",
    "raw": {
      "id": "task_xxx"
    }
  }
}

然后可轮询：

GET /v1/video/generations/:taskId

建议每 5 秒查询一次，直到任务状态变为 success 或 failed。

11. 补充说明

视频参考只支持 http/https URL
音频支持 URL 或 Base64
图片支持 URL 或 Base64
watermark 默认 false
当前文档描述的是“客户端调用当前网关”的方式，不是客户端直连火山官方接口的原始 content 格式

12. 山河2.0-fast同山河2.0参数一致，替换模型名称即可

谜镜API调动接口文档