产品文档

Doubao-文本对话 ​

用于多轮对话、推理与结构化生成。请求/响应字段与火山方舟对话 API 保持兼容，详见 官方 · 对话(Chat) API。

URL：/v3/chat/completions

Method：POST

授权 ​

Authorization ​

  • 类型 string · 位置 header · 必填
  • 认证方式 HTTP: Bearer Auth
  • 说明 请求头格式为 Authorization: Bearer <API_KEY>。请在 公共参数 中获取并设置。

请求头 ​

Content-Type ​

  • 类型 字符串枚举 · 默认值 application/json · 必填
  • 说明 请求体须为 JSON。

请求体 ​

以下描述的是 JSON 请求体字段；Authorization 与 Content-Type 见上文。

model ​

  • 类型 string · 必填
  • 说明 模型名称。填平台模型名 Doubao-Seed-2.0-Pro（控制台模型列表与 GET /v1/models 中显示的名字）；也接受该模型的 provider_model_id doubao-seed-2-0-pro-260215。

messages ​

  • 类型 object[] · 必填
  • 说明 对话消息列表，元素为 Message 对象。

Message 单条 ​

  • role（string，必填）：角色，分为 system / user / assistant / tool。
  • content（角色相关，必填）：不同 role 的 content 结构不同。

role=system 系统消息 ​

  • role（string，必填）：发送消息的角色，此处应为 system。
  • content（string | object[]，必填）：系统消息内容。可传纯文本，或按多模态内容数组传入。
  • content 子段说明：
    • 纯文本内容：content 为 string，表示系统消息文本。
    • 多模态内容：content 为 object[]，每个元素是一个内容片段。
    • 文本片段（type=text）：
      • type（string，必选）：此处应为 text。
      • text（string，必选）：文本模态部分内容。
    • 图片片段（type=image_url）：
      • type（string，必选）：此处应为 image_url。
      • image_url（object，必选）：图片模态内容对象。
      • image_url.url（string，必选）：支持图片链接或图片 Base64 编码。
      • image_url.detail（string，可选）：取值范围 low、high、xhigh，用于控制图片理解精细度。
    • 视频片段（type=video_url）：
      • type（string，必选）：此处应为 video_url。
      • video_url（object，必选）：视频模态内容对象。
      • video_url.url（string，必选）：支持视频链接或视频 Base64 编码（详见视频理解说明）。
      • video_url.fps（float | null，默认值 1）：取值范围 [0.2, 5]。
        • 取值越高，对视频中画面变化越敏感。
        • 取值越低，对视频中画面变化越迟钝，但 token 花费少，速度更快。

role=user 用户消息 ​

  • role（string，必选）：发送消息的角色，此处应为 user。
  • content（string | object[]，必选）：用户信息内容。
  • content 子段说明：
    • 纯文本内容（string）：文本消息内容。
    • 多模态内容（object[]）：支持文本、图片、视频等模态内容。
    • 文本片段（object）：
      • text（string，必选）：文本模态部分内容。
      • type（string，必选）：内容模态，此处应为 text。
    • 图片片段（object）：
      • type（string，必选）：内容模态，此处应为 image_url。
      • image_url（object，必选）：图片模态内容对象。
      • image_url.url（string，必选）：支持图片链接或图片 Base64 编码。
      • image_url.detail（string | null，可选）：取值范围 low、high、xhigh。
      • image_url.image_pixel_limit（object | null，默认 null）：输入给模型的图片像素范围；超出范围会等比例缩放到该范围。
        • 图片像素范围需在 [196, 36000000]，否则会直接报错。
        • 生效优先级：高于 detail；同时配置时，以 image_pixel_limit 为准。
        • 未设置 image_pixel_limit 时，使用 detail 对应的 min_pixels / max_pixels。
        • image_url.image_pixel_limit.max_pixels（integer）：图片最大像素限制。
          • doubao-seed-1.8 之前模型范围：(min_pixels, 4014080]
          • doubao-seed-1.8、doubao-seed-2.0 模型范围：(min_pixels, 9031680]
        • image_url.image_pixel_limit.min_pixels（integer）：图片最小像素限制。
          • doubao-seed-1.8 之前模型范围：[3136, max_pixels)
          • doubao-seed-1.8、doubao-seed-2.0 模型范围：[1764, max_pixels)
    • 视频片段（object）：
      • type（string，必选）：内容模态，此处应为 video_url。
      • video_url（object，必选）：视频模态内容对象。
      • video_url.url（string，必选）：支持视频链接或视频 Base64 编码（详见视频理解说明）。
      • video_url.fps（float | null，默认值 1）：取值范围 [0.2, 5]。
        • 取值越高，对视频中画面变化越敏感。
        • 取值越低，对视频中画面变化越迟钝，但 token 花费少，速度更快。

role=assistant 模型消息 ​

  • role（string，必选）：发送消息的角色，此处应为 assistant。
  • content（string | array）：模型消息内容。
  • reasoning_content（string）：模型消息中思维链内容。仅模型 doubao-seed-1.8、deepseek-v3.2、doubao-seed-2.0 支持该字段。
  • tool_calls（object[]）：模型消息中的工具调用部分。
  • 约束：content 与 tool_calls 至少填写一项。
  • tool_calls 子段说明：
    • tool_calls.function（object，必选）：模型返回的需调用函数信息。
      • tool_calls.function.name（string，必选）：需调用的函数名称。
      • tool_calls.function.arguments（string，必选）：需调用函数入参，JSON 格式。
        • 模型并不总是生成有效 JSON，可能会虚构未定义参数；建议调用前先校验参数有效性。
    • tool_calls.id（string，必选）：需调用工具 ID，由模型生成。
    • tool_calls.type（string，必选）：消息类型，当前仅支持 function。

role=tool 工具消息 ​

  • role（string，必选）：发送消息的角色，此处应为 tool。
  • content（string | array，必选）：工具返回的消息。
  • tool_call_id（string，必选）：模型生成需调用工具请求时返回的 ID。程序调用工具后的返回需要附上同一 ID，用于关联工具结果与模型请求，避免多工具调用时信息混淆。

thinking ​

  • 类型 object · 可选 · 默认值 {"type":"enabled"}
  • 说明 控制模型是否开启深度思考模式。不同模型是否支持以及默认取值可能不同，请以对应模型文档为准。

thinking.type ​

  • 类型 string · 必选
  • 取值范围 enabled、disabled、auto
  • 说明：
    • enabled：开启思考模式，模型强制先思考再回答。
    • disabled：关闭思考模式，模型直接回答问题，不进行思考。
    • auto：自动思考模式，模型根据问题自主判断是否需要思考，简单题直接回答。

stream ​

  • 类型 boolean | null · 可选 · 默认 false
  • 说明 响应内容是否流式返回：
    • false：模型生成所有内容后一次性返回结果。
    • true：按 SSE 协议逐段返回，data: [DONE] 消息结束。当 stream=true 时，可设置 stream_options 字段以获取 token 用量统计信息。

stream_options ​

  • 类型 object | null · 可选
  • 说明 流式返回选项；仅在 stream=true 时生效。

include_usage ​

  • 类型 boolean | null
  • 说明 在 data: [DONE] 前额外返回本次请求总 token 用量。

chunk_include_usage ​

  • 类型 boolean | null
  • 说明 在每个 chunk 中返回截至当前的累计 token 用量。

max_tokens ​

  • 类型 integer · 可选
  • 说明 本次回复最大生成 token 数。用于限制输出长度与成本。

max_completion_tokens ​

  • 类型 integer · 可选
  • 说明 兼容写法，表示本次回复最大生成 token 数；与 max_tokens 二选一或二者保持一致。

service_tier ​

  • 类型 string | null · 可选 · 默认 auto
  • 说明 服务等级，常见可选 auto、default。

stop ​

  • 类型 string | string[] · 可选
  • 说明 停止词。命中后模型会停止继续生成。

reasoning_effort ​

  • 类型 string | null · 可选 · 默认 medium
  • 说明 思考强度，常见可选 minimal、low、medium、high。一般强度越高，推理更充分、耗时与成本也可能更高。

response_format ​

  • 类型 object · 可选
  • 说明 结构化输出配置，常见为 json_schema。

type ​

  • 类型 string
  • 说明 常见为 json_schema。

json_schema.name ​

  • 类型 string
  • 说明 结构化输出名称。

json_schema.schema ​

  • 类型 object
  • 说明 JSON Schema 定义对象。

json_schema.strict ​

  • 类型 boolean
  • 说明 是否严格约束输出格式。

frequency_penalty ​

  • 类型 number · 可选 · 默认 0
  • 说明 频率惩罚，常见范围 [-2.0, 2.0]。

presence_penalty ​

  • 类型 number · 可选 · 默认 0
  • 说明 存在惩罚，常见范围 [-2.0, 2.0]。

temperature ​

  • 类型 number · 可选
  • 说明 温度参数，用于调节随机性。值越高越发散，值越低越稳定。

top_p ​

  • 类型 number · 可选
  • 说明 核采样参数（Nucleus Sampling），与 temperature 共同影响生成分布。

logprobs ​

  • 类型 boolean | null · 可选
  • 说明 是否返回输出 token 的对数概率信息。

top_logprobs ​

  • 类型 integer | null · 可选
  • 说明 返回每个位置概率最高的 Top-N token 对数概率（通常需与 logprobs=true 搭配）。

logit_bias ​

  • 类型 object | null · 可选
  • 说明 对指定 token 的采样倾向施加偏置。键为 token id（字符串），值为偏置分值（常见 -100 到 100）。

tools ​

  • 类型 object[] | null · 可选
  • 说明 可供模型调用的工具定义列表。

tools[].type ​

  • 类型 string
  • 说明 工具类型，当前常用 function。

tools[].function.name ​

  • 类型 string
  • 说明 函数名称，需与服务端实际可调用函数一致。

tools[].function.description ​

  • 类型 string
  • 说明 函数用途说明，帮助模型理解何时调用该工具。

tools[].function.parameters ​

  • 类型 object
  • 说明 函数入参的 JSON Schema 定义。

parallel_tool_calls ​

  • 类型 boolean | null · 可选
  • 说明 是否允许模型并行发起多个工具调用。

tool_choice ​

  • 类型 string | object | null · 可选
  • 说明 控制模型工具选择策略（如自动选择、强制某个工具或禁止工具调用）。

字符串模式 ​

  • 说明 常见 auto（自动选择）、none（不调用工具）、required（必须调用工具）。

对象模式 ​

  • 说明 可指定固定工具，例如 {"type":"function","function":{"name":"my_func"}}。

非流式 · 响应 ​

成功时一般为 200，正文 application/json。常见字段如下。

id ​

  • 类型 string
  • 说明 本次响应 ID。

object ​

  • 类型 string
  • 说明 对象类型，非流式常见为 chat.completion。

created ​

  • 类型 integer
  • 说明 响应创建时间（Unix 时间戳，秒）。

choices ​

  • 类型 object[]
  • 说明 候选结果；通常取 choices[0].message.content 作为助手完整回复。

choices[].index ​

  • 类型 integer
  • 说明 候选下标（从 0 开始）。

choices[].finish_reason ​

  • 类型 string | null
  • 说明 结束原因。常见：stop、length、tool_calls、content_filter。

choices[].message ​

  • 类型 object
  • 说明 助手消息对象（role=assistant）。
  • message.role（string）：通常为 assistant。
  • message.content（string | array | null）：模型回复内容。
  • message.reasoning_content（string，可选）：模型思维链文本（模型支持时返回）。
  • message.tool_calls（object[]，可选）：模型要求调用工具时返回。

choices[].logprobs ​

  • 类型 object | null
  • 说明 当 logprobs=true 时返回 token 概率相关信息。

model ​

  • 类型 string
  • 说明 实际使用的模型 ID。

usage ​

  • 类型 object
  • 说明 用量统计，常见含 prompt_tokens、completion_tokens、total_tokens；部分模型可能返回推理 token 统计。

usage.prompt_tokens ​

  • 类型 integer
  • 说明 输入消耗 token 数。

usage.completion_tokens ​

  • 类型 integer
  • 说明 输出消耗 token 数。

usage.total_tokens ​

  • 类型 integer
  • 说明 总 token 数（输入+输出）。

流式 · 响应 ​

  • Content-Type text/event-stream（stream: true 时）

传输格式 ​

  • 说明 采用 SSE：多行 data:，每行是 JSON 片段。增量正文常见于 choices[0].delta.content；若启用 stream_options.include_usage，结束前可返回 usage 统计。

常见流式分片字段 ​

  • id：请求 ID（与整次对话对应）
  • object：常见为 chat.completion.chunk
  • created：分片时间戳
  • model：模型 ID
  • choices[].index：候选下标
  • choices[].delta.role：通常首包出现
  • choices[].delta.content：增量文本内容
  • choices[].delta.tool_calls：增量工具调用信息（有工具时）
  • choices[].finish_reason：分片结束原因（末包出现）
  • usage：开启统计时可能在尾包返回

错误响应（常见） ​

  • HTTP 状态码：常见 400、401、403、429、500
  • 错误体：通常为 error 对象，包含 message、type、code 等字段
  • 排查建议：
    • 先核对 Authorization 与模型权限
    • 再检查 messages 结构、tools schema、多模态字段格式
    • 发生限流时结合重试与退避策略处理

cURL 示例（非流式） ​

bash
curl -X POST "$BASE_URL/v3/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Doubao-Seed-2.0-Pro",
    "messages": [
      {
        "role": "system",
        "content": "你是一个专业、简洁的中文助手。"
      },
      {
        "role": "user",
        "content": "请给我三条 Agent 场景落地建议。"
      }
    ],
    "thinking": {
      "type": "auto"
    },
    "stream": false,
    "stream_options": {
      "include_usage": true,
      "chunk_include_usage": false
    },
    "max_tokens": 2048,
    "max_completion_tokens": 2048,
    "service_tier": "auto",
    "stop": ["</end>"],
    "reasoning_effort": "medium",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "structured_output",
        "strict": false,
        "schema": {
          "type": "object",
          "properties": {
            "summary": { "type": "string" },
            "bullets": { "type": "array", "items": { "type": "string" } }
          },
          "required": ["summary", "bullets"]
        }
      }
    },
    "frequency_penalty": 0,
    "presence_penalty": 0,
    "temperature": 0.7,
    "top_p": 0.95,
    "logprobs": false,
    "top_logprobs": null,
    "logit_bias": null,
    "tools": null,
    "parallel_tool_calls": false,
    "tool_choice": "auto"
  }'