## 授权
### `Authorization`
- **类型** `string` · **位置** `header` · **必填**
- **认证方式** **HTTP: Bearer Auth**
- **说明** 请求头格式为 `Authorization: Bearer
`。请在 [公共参数](api-common.md) 中获取并设置。
## 请求头
### `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 概率相关信息。
#### `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、多模态字段格式
- 发生限流时结合重试与退避策略处理