API 文档
v3
根地址—

快速开始

API 根地址—
认证方式Bearer Token,请求头携带 Authorization: Bearer YOUR_API_KEY(可在「密钥管理」中查看)
数据格式请求与响应均为 application/json,字符编码 UTF-8
接口协议智能对话为同步的 OpenAI 兼容协议,单次请求直接返回结果;视频生成为异步任务式:先创建任务拿到任务 ID,再轮询查询获取视频地址

调用流程#

1
创建任务
POST /v3/contents/generations/tasks
提交生成参数,立即返回任务 id(不是视频本身)
2
轮询查询
GET /v3/.../tasks/{id}
建议提交后 20~30 秒首查,之后每 10~20 秒查一次
3
获取视频
状态变为 succeeded 后,从 content.video_url 下载视频,链接 24 小时过期,请及时转存

创建视频生成任务

POST /v3/contents/generations/tasks

支持模型#

模型 ID说明分辨率时长范围
doubao-seedance-2-5-260628Seedance 2.5,最新旗舰,支持 30 秒长片、视频编辑与延长480p / 720p / 1080p4~30 秒 或 -1(智能选时长)
doubao-seedance-2-0-260128Seedance 2.0 标准版480p / 720p / 1080p4~15 秒
doubao-seedance-2-0-fast-260128Seedance 2.0 Fast 极速版,出片更快480p / 720p4~15 秒
doubao-seedance-2-0-mini-260615Seedance 2.0 Mini 轻量版,价格更低480p / 720p4~15 秒
平台实际可用的模型、分辨率与价格以「模型广场」为准,管理员可在后台动态上下架模型。

请求参数#

参数类型必填默认值说明
modelstring必填-模型 ID,见上表
contentarray必填-输入内容数组,由 text / image_url / video_url / audio_url 组成,决定生成模式(见下方)
resolutionstring可选720p分辨率档位:480p / 720p / 1080p(1080p 仅 2.5 与 2.0 标准版支持),同档位全比例同价
ratiostring可选16:9宽高比:21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive(按输入素材自动适配,图生视频推荐)
durationint可选5视频时长(整数秒)。2.5 支持 4~30,2.0 系支持 4~15;2.5 可传 -1 由模型智能选择时长(按实际产出计费,建议显式指定)
generate_audiobool可选true是否生成与画面同步的音频(人声/音效/配乐,单声道)。不需要声音请显式传 false
watermarkbool可选false是否在画面右下角添加「AI 生成」水印
seedint可选-1随机种子,取值 [-1, 2³²-1]。相同 seed 生成相似(不保证完全一致)的结果,可用于复现风格
return_last_framebool可选false是否返回视频尾帧 PNG(无水印),可用作下一段任务的首帧,实现多段视频接力
execution_expires_afterint可选172800任务过期阈值(秒),超时任务标记为 expired,取值 [3600, 259200]
output_formatstring可选mp4仅 2.5:mp4(通用)/ mov(色彩还原更好,适合后期,部分播放器不兼容)
omni_reference_task_typestring可选auto仅 2.5:auto / edit(视频编辑)/ extend(视频延长),显式指定可在提交时前置校验参数

生成模式#

由 content 数组的组合决定,三种图生场景互斥。

模式content 组成role 取值
文生视频1 个 text(提示词)-
图生视频 - 首帧text(可选)+ 1 个 image_urlfirst_frame 或不填
图生视频 - 首尾帧text(可选)+ 2 个 image_url必填 first_frame / last_frame
多模态参考生视频text + 参考素材(2.0 系:最多 9 图 + 3 视频 + 3 音频,且至少含 1 图或 1 视频;2.5:最多 30 图 + 10 视频 + 10 音频,音频可单独使用)reference_image / reference_video / reference_audio
视频编辑(仅 2.5)text(须含「增加/删除/修改/替换」等编辑意图词,用 @视频1 指代素材)+ 至少 1 个 video_url(时长 4~30 秒)reference_video,需 ratio=adaptive、duration=-1
视频延长(仅 2.5)text(须含「向后延长/续写/延续」等意图词)+ 至少 1 个 video_urlreference_video,需 ratio=adaptive
素材说明:图片支持公网 URL、Base64(data:image/png;base64,...),格式 jpeg/png/webp/bmp/tiff 等,单张 < 30MB,宽高比 (0.4, 2.5),边长 (300, 6000)px;参考音频支持 wav/mp3,单段 2~15 秒。不支持含真人人脸的输入素材。
不支持 Seedance 1.x 的 frames、camera_fixed 参数,传入会被忽略或报错。

请求示例#

① 文生视频

bash
curl -X POST {{BASE}}/v3/contents/generations/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "无人机航拍视角飞越秋天的山谷,金黄色的森林和蜿蜒的河流,电影感"}
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

② 首尾帧图生视频

json
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "画面从第一帧平滑过渡到最后一帧,镜头缓慢推进"},
    {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
    {"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"}
  ],
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": 5
}

③ 多模态参考生视频

json
{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {"type": "text", "text": "以参考图的角色和风格,生成角色在雨夜街头行走的镜头"},
    {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"}
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

创建成功响应

仅返回任务 ID,需再轮询查询接口获取视频。

json
{
  "id": "cgt-20260606160057-xxxxx"
}

查询视频生成任务

GET /v3/contents/generations/tasks/{task_id}

任务状态机#

queued排队中 → running生成中 → succeeded成功 ✓
或进入终态: failed失败 expired过期

轮询建议:视频生成是分钟级任务(720p 5 秒约 90~150 秒),首次查询建议在提交后 20~30 秒,之后每 10~20 秒查询一次;超过 10 分钟未到终态可视为异常。

任务成功响应示例

json
{
  "id": "cgt-20260606160057-xxxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://xxx.tos-cn-beijing.volces.com/xxx.mp4?X-Tos-Expires=86400..."
  },
  "usage": { "completion_tokens": 108900, "total_tokens": 108900 },
  "created_at": 1780732857,
  "updated_at": 1780732991,
  "seed": 97151,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true
}
视频地址在 content.video_url(不在顶层),为签名直链,24 小时过期,请在任务成功后立即下载转存;下载直链时不要携带 Authorization 头。
传入 duration: -1 或 ratio: adaptive 时,实际时长与比例以响应中的 duration / ratio 字段为准。

Python 完整示例(创建 → 轮询 → 下载)#

python
import time, requests

BASE = "{{BASE}}/v3/contents/generations/tasks"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}

# 1. 创建任务
task_id = requests.post(BASE, json={
    "model": "doubao-seedance-2-0-260128",
    "content": [{"type": "text", "text": "海浪拍打礁石,夕阳把海面染成金色,慢镜头"}],
    "resolution": "720p", "ratio": "16:9", "duration": 5
}, headers=HEADERS, timeout=60).json()["id"]

# 2. 轮询直到终态
while True:
    time.sleep(20)
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    if task.get("status") in ("succeeded", "failed", "expired"):
        break

# 3. 下载视频(24 小时过期,成功后立即转存)
if task["status"] == "succeeded":
    video = requests.get(task["content"]["video_url"], stream=True, timeout=300)
    with open(f"{task_id}.mp4", "wb") as f:
        for chunk in video.iter_content(1 << 20):
            f.write(chunk)

账户接口

查询账户信息

GET /v1/me

返回当前 API Key 的账户信息:

json
{
  "code": 0,
  "data": {
    "client_name": "客户名称",
    "balance": 95.50,          // 账户余额(元)
    "total_recharge": 100.00,  // 累计充值(元)
    "total_consumed": 4.50,    // 累计消费(元)
    "status": 1,
    "created_at": "2026-01-01 12:00:00"
  }
}

查询调用记录

GET /v1/usage?page=1&page_size=20

可选筛选参数:date_from / date_to(格式 YYYY-MM-DD)、status(pending / running / succeeded / failed)。返回分页的调用记录列表(含任务 ID、模型、状态、费用、时间)。

计费说明

平台与火山方舟官方保持一致,按 token 计费,单价单位为 元 / 百万 token。计费公式:

费用 = token 用量 ÷ 1,000,000 × 单价(元/百万token)

token 用量按官方公式估算:token ≈(输入视频时长 + 输出视频时长)× 宽 × 高 × 帧率 ÷ 1024(帧率默认 24)。分辨率档位对应的标准像素面积如下:

分辨率标准尺寸(宽×高)分辨率标准尺寸(宽×高)
480p854 × 4801080p1920 × 1080
720p1280 × 7202K / 4K2560 × 1440 / 3840 × 2160

同一模型「含视频输入」与「不含视频输入」为两档不同单价,各分辨率的具体单价以「模型广场」价格表为准。

计费流程:创建任务时按预估 token 用量预扣押金;任务到达终态后,以上游返回的真实 usage.completion_tokens(见「查询任务」响应)× 单价快照重新结算,多退少补——预估高于实际退回差额,低于实际补扣差额。任务失败 / 过期不产生视频费用,预扣押金全额退回。实际扣费金额可在「调用记录」中查询。

对话计费规则#

智能对话按输入 / 输出 token 分别计价,单价单位同为 元 / 百万 token:

费用 = 输入 token × 输入单价 + 输出 token × 输出单价

提交请求时按「输入内容估算 token + max_tokens」预扣押金(余额不足直接拒绝请求),响应完成后按真实 usage(prompt_tokens / completion_tokens)结算,多退少补;上游请求失败自动全额退回预扣款。客户分组折扣自动生效,各模型输入 / 输出单价见「模型广场」。

错误码说明

错误码说明处理建议
400请求参数错误(如模型不支持该分辨率、duration 超出范围、非法 ratio)根据返回的 msg 修正参数,参数错误不扣费
401API Key 无效或已被禁用检查 Authorization 头,或到「密钥管理」确认 Key 状态
402账户余额不足到「财务管理」提交充值申请
404任务不存在确认任务 ID 是否正确、是否属于当前 API Key
502上游服务请求失败稍后重试,持续失败请联系平台客服
503当前无可用通道平台通道繁忙,请稍后重试

智能对话(Chat Completions)

对话模型采用 OpenAI 兼容协议,同步返回:单次 HTTP 请求内直接拿到完整回答,无需轮询。可直接使用 OpenAI / DeepSeek 等通用 SDK,仅需将 base_url 指向平台根地址(—)+ /v1。视频生成仍为异步任务协议,见上方章节。

POST /v1/chat/completions

可用模型#

先调用模型列表接口获取当前已启用的对话模型(与「模型广场」一致,管理员可动态上下架):

GET /v1/models
json
{
  "object": "list",
  "data": [
    { "id": "glm-5.3", "object": "model", "created": 1781721600, "owned_by": "ai-gateway" },
    { "id": "deepseek-chat", "object": "model", "created": 1781721600, "owned_by": "ai-gateway" }
  ]
}
以上仅为示例结构,实际可用模型以 /v1/models 返回为准;各模型输入 / 输出单价见「模型广场」。

请求参数#

参数类型必填默认值说明
modelstring必填-对话模型 ID,取值见 GET /v1/models
messagesarray必填-对话消息数组,每项为 {"role": "...", "content": "..."};role 支持 system / user / assistant / tool,content 为纯文本
streambool可选false是否以 SSE 流式返回,见下方「流式输出」
max_tokensint可选1024最大生成 token 数,原值透传给上游(不限制上限),同时作为预扣费估算依据
temperature / top_p / stop 等-可选-其余 OpenAI 常规参数原样透传给上游模型
toolsarray可选-工具调用(Function Calling),格式与 OpenAI 一致,原样透传给上游模型;模型会在响应中返回 tool_calls,由客户端执行后将结果作为 tool 角色消息回传
response_formatobject可选-响应格式控制,如 {"type": "json_object"} 启用 JSON mode,原样透传给上游模型
functionsarray可选-旧版函数调用接口(已被 tools 取代),原样透传给上游模型
已支持 tools(Function Calling)、response_format(JSON mode)、functions 等 OpenAI 标准参数,均原样透传给上游模型。
同步请求受渠道超时限制,长回答建议开启 stream(流式无总时长限制),并将客户端读超时设置在 120 秒以上。

响应格式#

非流式响应结构与 OpenAI 完全一致,usage 为最终结算依据:

json
{
  "id": "chatcmpl-20261014120000-x1",
  "object": "chat.completion",
  "created": 1781721600,
  "model": "glm-5.3",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "长沙市,湖南省省会……" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 14, "completion_tokens": 356, "total_tokens": 370 }
}

出错时返回 OpenAI 风格错误体(HTTP 状态码非 2xx):

json
{
  "error": {
    "message": "余额不足,无法预扣本次最大可能费用",
    "type": "insufficient_quota",
    "param": null,
    "code": null
  }
}
状态码场景与处理建议
400缺少 model / messages、role 非法等请求参数错误
401API Key 无效或已被禁用,到「密钥管理」确认 Key 状态
402账户余额不足,无法预扣本次最大可能费用(type 为 insufficient_quota)
404模型不存在或未启用(param 为 model),以 /v1/models 返回为准
429上游限流,请稍后重试
502上游聊天服务请求失败,预扣费自动全额退回
503暂无可用聊天渠道,或该模型未配置有效售价

流式输出#

请求体中传 "stream": true,响应为标准 text/event-stream(SSE),分片结构与 OpenAI 一致,以 data: [DONE] 结束,OpenAI SDK 流式模式可直接消费。建议同时传 "stream_options": {"include_usage": true},结束前会额外收到一个含 usage 的分片,平台按其精确结算;若整个流中未收到 usage,则按预扣金额作为最终费用,不做差额退补。

sse
data: {"id":"chatcmpl-x1","object":"chat.completion.chunk","created":1781721600,"model":"glm-5.3","choices":[{"index":0,"delta":{"role":"assistant","content":"长"},"finish_reason":null}]}

data: {"id":"chatcmpl-x1","object":"chat.completion.chunk","created":1781721600,"model":"glm-5.3","choices":[{"index":0,"delta":{"content":"沙"},"finish_reason":null}]}

data: {"id":"chatcmpl-x1","object":"chat.completion.chunk","created":1781721600,"model":"glm-5.3","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":52,"total_tokens":66}}

data: [DONE]

请求示例#

① cURL(同步非流式)

bash
curl -X POST {{BASE}}/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "messages": [
      {"role": "system", "content": "你是一个乐于助人的中文助手"},
      {"role": "user", "content": "介绍长沙市的特色"}
    ],
    "max_tokens": 4096
  }'

② cURL(流式)

bash
curl -X POST {{BASE}}/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "messages": [{"role": "user", "content": "用三句话介绍长沙市"}],
    "max_tokens": 4096,
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

③ Python(OpenAI SDK)

python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="{{BASE}}/v1"  # 指向平台网关
)

resp = client.chat.completions.create(
    model="glm-5.3",
    messages=[
        {"role": "system", "content": "你是一个乐于助人的中文助手"},
        {"role": "user", "content": "介绍长沙市的特色"}
    ],
    max_tokens=4096
)
print(resp.choices[0].message.content)
print(resp.usage)  # 输入 / 输出 token 用量,即最终结算依据

使用 DeepSeek SDK、LangChain 等其他框架同理:base_url 指向平台、api_key 换成平台密钥即可。

④ cURL(工具调用 / Function Calling)

bash
curl -X POST {{BASE}}/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "messages": [{"role": "user", "content": "北京今天天气怎么样?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的实时天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "城市名称"}
          },
          "required": ["city"]
        }
      }
    }]
  }'

模型会在响应的 tool_calls 中返回函数调用建议,客户端执行后将结果以 role: "tool" 的消息回传,模型据此生成最终回答。

计费提示:对话按输入 / 输出 token 分别计价(元 / 百万 token),提交时预扣、响应后按真实 usage 多退少补,详见「计费说明 → 对话计费规则」。