OpenAI Chat API 参考

POST

/compatible-mode/v1/chat/completions

import os
from openai import OpenAI

client = OpenAI(
  # 若未设置环境变量，请将下一行替换为：api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
  model="qwen3.6-plus",
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Who are you?"},
  ],
  # extra_body={"enable_thinking": False},
)
print(completion.model_dump_json())

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "I am a large-scale language model developed by Alibaba Cloud. My name is Qwen."
      },
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null
    }
  ],
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 3019,
    "completion_tokens": 104,
    "total_tokens": 3123,
    "prompt_tokens_details": {
      "cached_tokens": 2048
    }
  },
  "created": 1735120033,
  "system_fingerprint": null,
  "model": "qwen3.6-plus",
  "id": "chatcmpl-6ada9ed2-7f33-9de2-8bb0-78bd4035025a"
}

鉴权

string

header

必填

千问云 API Key。详见获取 API Key。

请求体

application/json

string

必填

使用的模型名称。支持通义千问大语言模型（商业版和开源版）、Qwen-VL、Qwen-Coder、Qwen-Omni、Qwen-Math、DeepSeek（阿里云直供、硅基流动直供、快手万擎直供）、Kimi（阿里云直供、月之暗面直供）、GLM（阿里云直供）、MiniMax（阿里云直供、稀宇科技直供）。

三方直供模型调用前需先在千问云控制台开通对应服务（以 SiliconFlow DeepSeek 为例：搜索 deepseek -> 找到 SiliconFlow DeepSeek 模型卡片 -> 单击立即开通 -> 确认授权）。

Qwen-Audio 不支持 OpenAI 兼容协议，仅支持 DashScope 协议。

具体模型名称及计费信息，请参见千问云控制台。

(System message · object | User message · object | Assistant message · object | Tool message · object)[]

必填

模型的对话历史，按时间顺序排列。

系统消息，用于为模型设定角色、语气、任务目标或约束条件。应置于 messages 数组的开头。QwQ 模型请勿设置系统消息；系统消息对 QVQ 模型无效。

System message
User message
Assistant message
Tool message

显示子属性

enum<string>

必填

系统消息的角色，固定为 system。

可选值：system

string

必填

系统指令，用于定义模型的角色、行为方式、回复风格和任务约束。

boolean

默认值false

启用流式输出模式。设置为 true 时，模型会边生成边输出，每生成一部分内容就立即返回一个数据块（chunk），您可以实时读取这些数据块拼接完整回复。开启此选项可提升阅读体验并降低超时风险。

object

流式输出的配置选项。仅在 stream 为 true 时生效。

显示子属性

boolean

默认值false

是否在响应的最后一个数据块中返回 Token 用量信息。

string[]

默认值["text"]

指定输出数据的模态。仅适用于 Qwen-Omni 模型。可选值：["text","audio"] 或 ["text"]。

object

输出音频的音色和格式。仅适用于 Qwen-Omni 模型，且需将 modalities 参数设置为 ["text","audio"]。

显示子属性

string

必填

输出音频使用的音色。详细信息请参见音色列表。

string

必填

输出音频的格式。目前仅支持 wav。

number

采样温度，控制生成文本的多样性。值越高，输出越多样；值越低，输出越确定。取值范围：大于等于 0 且小于 2。temperature 和 top_p 均可控制生成多样性，二者只需设置其中一个。QVQ 模型请勿修改默认温度值。

第三方模型默认 temperature 值：

DeepSeek 系列（阿里云直供）：deepseek-v4-pro、deepseek-v4-flash、deepseek-v3.2（非思考模式）: 1.0；deepseek-v3.2（思考模式）、deepseek-v3.2-exp、deepseek-v3.1、deepseek-r1、deepseek-r1-0528、deepseek-r1-distill-qwen 蒸馏版: 0.6；deepseek-v3: 0.7
DeepSeek 系列（硅基流动直供）：siliconflow/deepseek-v3.2、siliconflow/deepseek-v3.1-terminus、siliconflow/deepseek-r1-0528、siliconflow/deepseek-v3-0324: 1.0
DeepSeek 系列（快手万擎直供）：vanchin/deepseek-v3.2-think（思考模式）: 0.6；vanchin/deepseek-v3.1-terminus: 0.7；vanchin/deepseek-v3.2-speciale、vanchin/deepseek-r1、vanchin/deepseek-v3、vanchin/deepseek-ocr: 1.0
Kimi 系列（阿里云直供）：kimi-k2.6（思考模式）、kimi-k2.5（思考模式）、kimi-k2-thinking: 1.0；kimi-k2.6（非思考模式）、kimi-k2.5（非思考模式）、Moonshot-Kimi-K2-Instruct: 0.6
Kimi 系列（月之暗面直供）：kimi/kimi-k2.6（思考模式）、kimi/kimi-k2.5（思考模式）: 1.0；kimi/kimi-k2.6（非思考模式）、kimi/kimi-k2.5（非思考模式）: 0.6
GLM 系列（阿里云直供）：glm-5.1、glm-5、glm-4.7、glm-4.6: 1.0；glm-4.5、glm-4.5-air: 0.6
MiniMax 系列（阿里云直供）：MiniMax-M2.5、MiniMax-M2.1: 1.0
MiniMax 系列（稀宇科技直供）：MiniMax/MiniMax-M2.7、MiniMax/MiniMax-M2.5、MiniMax/MiniMax-M2.1: 1.0

number

核采样的概率阈值。top_p 值越高，生成文本越多样；值越低，输出越确定。取值范围：(0, 1.0]。temperature 和 top_p 均可控制生成多样性，二者只需设置其中一个。QVQ 模型请勿修改默认 top_p 值。

第三方模型默认 top_p 值：

DeepSeek 系列（阿里云直供）：deepseek-v4-pro、deepseek-v4-flash、deepseek-v3.2、deepseek-v3.2-exp、deepseek-v3.1、deepseek-r1、deepseek-r1-0528、deepseek-r1-distill-qwen 蒸馏版: 0.95；deepseek-v3: 0.6
DeepSeek 系列（硅基流动直供）：siliconflow/deepseek-v3.2、siliconflow/deepseek-v3.1-terminus、siliconflow/deepseek-r1-0528、siliconflow/deepseek-v3-0324: 1.0
DeepSeek 系列（快手万擎直供）：vanchin/deepseek-v3.2-think、vanchin/deepseek-v3.1-terminus: 0.95；vanchin/deepseek-v3.2-speciale: 0.9；vanchin/deepseek-r1: 0.8；vanchin/deepseek-v3、vanchin/deepseek-ocr: 1.0
Kimi 系列（阿里云直供）：kimi-k2.6、kimi-k2.5、kimi-k2-thinking: 0.95；Moonshot-Kimi-K2-Instruct: 1.0
Kimi 系列（月之暗面直供）：kimi/kimi-k2.6、kimi/kimi-k2.5: 0.95
GLM 系列（阿里云直供）：0.95
MiniMax 系列（阿里云直供）：MiniMax-M2.5、MiniMax-M2.1: 0.95
MiniMax 系列（稀宇科技直供）：MiniMax/MiniMax-M2.7、MiniMax/MiniMax-M2.5、MiniMax/MiniMax-M2.1: 0.9

integer

生成时用于采样的候选 Token 数量。值越大，输出越随机；值越小，输出越确定。设置为 null 或大于 100 时，top_k 策略禁用，仅 top_p 生效。取值须为大于等于 0 的整数。

各模型默认 top_k 值：

QVQ 系列、qwen-vl-plus-2025-07-10 和 qwen-vl-plus-2025-08-15：10
QwQ 系列：40
其他 qwen-vl-plus 系列、qwen-vl-max-2025-08-13 之前的模型、qwen2.5-omni-7b：1
Qwen3-Omni-Flash 系列：50
GLM 系列（阿里云直供）：20
DeepSeek/Kimi/MiniMax 系列均不支持 top_k 参数
其他所有模型：20

QVQ 模型请勿修改默认 top_k 值。

此参数不是标准 OpenAI 参数。 使用 Python SDK 时，请通过 extra_body 传入：extra_body={"top_k": xxx}。

number

控制模型避免重复内容的强度。取值范围：-2.0 到 2.0。正值降低重复性，负值增加重复性。创意写作或头脑风暴场景可适当提高此值；技术文档或正式文本场景可适当降低此值。

各模型默认 presence_penalty 值：

Qwen3.6（非思考模式）、Qwen3.5（非思考模式）、qwen3-max-preview（思考模式）、Qwen3（非思考模式）、Qwen3-Instruct 系列、qwen3-0.6b/1.7b/4b（思考模式）、QVQ 系列、qwen-max、qwen-max-latest、qwen2.5-vl 系列、qwen-vl-max 系列、qwen-vl-plus、Qwen3-VL（非思考模式）：1.5
qwen-vl-plus-latest、qwen-vl-plus-2025-08-15：1.2
qwen-vl-plus-2025-01-25：1.0
qwen3-8b/14b/32b/30b-a3b/235b-a22b（思考模式）、qwen-plus/qwen-plus-latest/2025-04-28（思考模式）、qwen-turbo/qwen-turbo/2025-04-28（思考模式）：0.5
DeepSeek 系列（阿里云直供）：deepseek-r1、deepseek-r1-0528、deepseek-r1-distill-qwen 蒸馏版: 1
Kimi 系列（阿里云直供）：kimi-k2.6、kimi-k2.5: 0.0
Kimi 系列（月之暗面直供）：0.0
MiniMax 系列（阿里云直供）：MiniMax-M2.5、MiniMax-M2.1: 0.0
其余 DeepSeek/Kimi/GLM/MiniMax 模型无默认值
其他所有模型：0.0

工作原理： 当参数值为正时，模型会对已出现在生成文本中的 Token 施加惩罚，惩罚力度与出现次数无关。这会降低这些 Token 再次出现的概率，从而减少重复并增加词汇多样性。

使用 qwen-vl-plus-2025-01-25 模型进行文字提取时，建议将 presence_penalty 设为 1.5。

QVQ 模型请勿修改默认 presence_penalty 值。

object

响应内容的格式。默认为 {"type": "text"}。

可选值：

{"type": "text"}：返回纯文本响应。
{"type": "json_object"}：返回符合标准 JSON 语法的字符串。
{"type": "json_schema", "json_schema": {...}}：返回符合自定义 Schema 的 JSON 字符串。

指定 {"type": "json_object"} 时，需在提示词中明确要求模型输出 JSON，例如添加"请以 JSON 格式输出"，否则会报错。

支持的模型列表，请参见结构化输出文档。

显示子属性

enum<string>

必填

格式类型。text 返回纯文本；json_object 返回符合标准 JSON 语法的字符串；json_schema 返回符合自定义 Schema 的 JSON 字符串。

可选值：text,json_object,json_schema

object

结构化输出的配置。当 type 为 json_schema 时必填。

显示子属性

string

必填

Schema 的唯一名称，只能包含字母、数字、下划线和连字符，最多 64 个字符。

string

Schema 用途的描述，帮助模型理解输出的语义上下文。

object

符合 JSON Schema 标准的对象，用于定义输出数据结构。

boolean

默认值false

是否要求模型严格遵循所有 Schema 约束。true（推荐）确保完全合规；false 可能导致输出不完全符合规范。

integer

响应中的最大 Token 数。达到此限制后停止生成，finish_reason 字段将被设置为 length。默认值和最大值对应模型的最大输出长度。max_tokens 不限制思维链的长度。

boolean

默认值false

将输入图片的最大像素上限提高至对应 16384 个 Token 的像素值。启用后，采用固定分辨率策略，max_pixels 设置将被忽略。若图片超出像素限制，系统会等比缩小至限制范围内。

vl_high_resolution_images 为 true 时的像素上限：

Qwen3.5 系列、Qwen3-VL 系列、qwen-vl-max、qwen-vl-max-latest、qwen-vl-max-0813、qwen-vl-plus、qwen-vl-plus-latest、qwen-vl-plus-0815：16,777,216（每个 Token 对应 32×32 像素，即 16,384×32×32）
QVQ 系列及其他 Qwen2.5-VL 系列模型：12,845,056（每个 Token 对应 28×28 像素，即 16,384×28×28）

若 vl_high_resolution_images 为 false，实际像素上限由 max_pixels 决定。

此参数不是标准 OpenAI 参数。 使用 Python SDK 时，请通过 extra_body 传入：extra_body={"vl_high_resolution_images": xxx}。

integer

默认值1

生成的响应数量，取值范围 1-4 的整数。适用于需要多个候选答案的场景，如创意写作或广告文案生成。仅 Qwen3（非思考模式）模型支持。传入 tools 参数时，请将 n 设为 1。增大 n 会增加输出 Token 消耗，但不影响输入 Token 消耗。

boolean

为混合思考模型启用思考模式。支持 Qwen3.6、Qwen3.5、Qwen3、Qwen3-Omni-Flash 和 Qwen3-VL 模型，以及 DeepSeek-V4-Pro/V4-Flash 系列（阿里云直供）、DeepSeek-V3.2/V3.2-exp/V3.1 系列（阿里云直供、硅基流动直供、快手万擎直供）、Kimi-K2.6/K2.5 系列（阿里云直供、月之暗面直供）、GLM 系列。DeepSeek-V4 系列默认开启思考，可通过 reasoning_effort 参数调整推理力度。启用后，思考内容将在 reasoning_content 字段中返回。

各模型的默认值不同。支持的模型及其默认 enable_thinking 值，请参见模型列表。

此参数不是标准 OpenAI 参数。 使用 Python SDK 时，请通过 extra_body 传入：extra_body={"enable_thinking": xxx}。

boolean

默认值false

是否将对话历史中 assistant 消息的 reasoning_content 拼接至模型输入。适用于需要模型参考历史思考过程的场景。目前支持 qwen3.6-max-preview、qwen3.6-plus、qwen3.6-plus-2026-04-02、kimi-k2.6。

若历史消息中不包含 reasoning_content，开启此参数不会报错，正常兼容。
开启后，历史对话中的 reasoning_content 会计入输入 Token 数量并计费。

此参数不是标准 OpenAI 参数。 使用 Python SDK 时，请通过 extra_body 传入：extra_body={"preserve_thinking": True}。

integer

思考过程的最大 Token 数。适用于 Qwen3.6、Qwen3.5、Qwen3-VL 以及 Qwen3 商业版和开源版模型。默认值为模型的最大思维链长度。详情请参见模型列表。

此参数不是标准 OpenAI 参数。 使用 Python SDK 时，请通过 extra_body 传入：extra_body={"thinking_budget": xxx}。

enum<string>

默认值"high"

控制 DeepSeek-V4 系列模型的推理力度。可选值：high（高力度推理）、max（最大力度推理）。low 和 medium 映射为 high，xhigh 映射为 max。适用于 deepseek-v4-pro、deepseek-v4-flash（阿里云直供）。

此参数不是标准 OpenAI 参数。 使用 Python SDK 时，请通过 extra_body 传入：extra_body={"reasoning_effort": "high"}。

可选值：high,max

boolean

默认值false

开启后，Function Calling 的 tool_call arguments 以流式增量方式返回，而非一次性返回。仅在 stream=true 时生效。适用于 glm-5.1、glm-5、glm-4.7、glm-4.6（阿里云直供）。

此参数不是标准 OpenAI 参数。 使用 Python SDK 时，请通过 extra_body 传入：extra_body={"tool_stream": true}。

boolean

默认值false

是否启用代码解释器功能。

此参数不是标准 OpenAI 参数。 使用 Python SDK 时，请通过 extra_body 传入：extra_body={"enable_code_interpreter": xxx}。

integer

随机数种子，用于保证结果可复现。在其他参数不变的情况下使用相同的种子值，模型会尽可能返回相同的结果。取值范围：[0, 2^31-1]。

boolean

默认值false

是否返回输出 Token 的对数概率。思考阶段生成的内容（reasoning_content）不包含对数概率。

支持的模型：

Qwen-plus 系列快照版（不含稳定版）
Qwen-turbo 系列快照版（不含稳定版）
Qwen3-vl-plus 模型（含稳定版）
Qwen3-vl-flash 模型（含稳定版）
Qwen3 开源模型

integer

默认值0

每个生成步骤返回的最可能候选 Token 数量。取值范围：0 到 5。仅在 logprobs 为 true 时生效。

string

停止词。生成文本中出现 stop 指定的字符串或 Token 时，立即停止生成。stop 为数组时，不能同时包含 token_id 和字符串类型的元素。

object[]

模型可在函数调用中使用的工具对象数组（支持一个或多个）。设置 tools 后，若模型判断需要调用工具，响应会在 tool_calls 字段中返回工具信息。使用示例请参见函数调用指南。

显示子属性

enum<string>

必填

工具类型。目前仅支持 function。

可选值：function

object

必填

显示子属性

string

必填

工具名称，只能包含字母、数字、下划线和连字符，最多 64 个 Token。

string

必填

工具的描述，帮助模型判断何时以及如何调用该工具。

object

默认值{}

使用合法 JSON Schema 描述工具的输入参数。为空时表示该工具无输入参数。

enum<string>

默认值"auto"

工具选择策略。auto 由模型自行决定；none 禁用工具调用；传入 {"type": "function", "function": {"name": "..."}} 对象可强制指定调用某个工具。处于思考模式的模型不支持强制指定工具。

boolean

默认值false

是否启用并行工具调用。

boolean

默认值false

启用联网搜索。开启后可能增加 Token 消耗。

此参数不是标准 OpenAI 参数。 使用 Python SDK 时，请通过 extra_body 传入：extra_body={"enable_search": True}。

object

联网搜索策略。仅在 enable_search 为 true 时生效。

属性说明：

forced_search（boolean，默认 false）：强制联网搜索。true 强制开启，false 由模型自行决定。
search_strategy（string，默认 turbo）：搜索规模策略。turbo 兼顾速度与效果；max 调用多个搜索引擎，策略更全面；agent 多次调用搜索和大模型进行多轮检索（仅适用于 qwen3.5-plus、qwen3.5-plus-2026-02-15、qwen3.5-flash、qwen3.5-flash-2026-02-23、qwen3-max、qwen3-max-2026-01-23、qwen3-max-2025-09-23、qwen3.5-omni-plus、qwen3.5-omni-plus-2026-03-15、qwen3.5-omni-flash 和 qwen3.5-omni-flash-2026-03-15）；agent_max 在 agent 策略基础上增加网页内容抽取（仅适用于思考模式下的 qwen3-max 和 qwen3-max-2026-01-23）。启用 agent 或 agent_max 时，仅支持返回搜索来源（enable_source: true），其他联网搜索功能不可用。
enable_search_extension（boolean，默认 false）：启用垂直领域搜索。

此参数不是标准 OpenAI 参数。 使用 Python SDK 时，请通过 extra_body 传入：extra_body={"search_options": xxx}。

显示子属性

boolean

默认值false

强制联网搜索。true 强制开启联网搜索，false 由模型自行决定。

enum<string>

默认值"turbo"

搜索规模策略。turbo（默认）兼顾速度与效果；max 调用多个搜索引擎，策略更全面，响应时间可能较长；agent 多次调用联网搜索和大模型进行多轮检索，仅适用于 qwen3.5-plus、qwen3.5-plus-2026-02-15、qwen3.5-flash、qwen3.5-flash-2026-02-23、qwen3-max、qwen3-max-2026-01-23、qwen3-max-2025-09-23、qwen3.5-omni-plus、qwen3.5-omni-plus-2026-03-15、qwen3.5-omni-flash 和 qwen3.5-omni-flash-2026-03-15；agent_max 在 agent 策略基础上增加网页内容抽取，仅适用于思考模式下的 qwen3-max 和 qwen3-max-2026-01-23。启用 agent 或 agent_max 时，仅支持返回搜索来源（enable_source: true）。

可选值：turbo,max,agent,agent_max

boolean

默认值false

启用垂直领域搜索。

响应

200-application/json

string

本次请求的唯一标识符。

object[]

模型生成内容的数组。

显示子属性

enum<string>

模型停止生成的原因。stop：自然结束或触发 stop 参数；length：达到最大输出长度；tool_calls：停止以调用工具。

可选值：stop,length,tool_calls

integer

当前对象在 choices 数组中的索引。

object | null

模型输出 Token 的对数概率信息。

显示子属性

object[]

Token 及其对应对数概率的数组。

显示子属性

string

当前 Token 的文本内容。

integer[]

当前 Token 的原始 UTF-8 字节列表。

number | null

当前 Token 的对数概率。null 表示概率极低。

object[]

当前位置最可能的候选 Token 列表。

显示子属性

string

候选 Token 的文本内容。

integer[]

该 Token 的原始 UTF-8 字节列表。

number | null

该候选 Token 的对数概率。

object

模型生成的消息。

显示子属性

string

模型响应的文本内容。

string

模型思维链推理过程的内容。

string | null

此字段固定为 null。

enum<string>

固定为 assistant。

可选值：assistant

object | null

此字段固定为 null。

object | null

（已废弃）此字段固定为 null，请改用 tool_calls。

object[]

模型发起函数调用后生成的工具及其输入参数信息。

显示子属性

string

本次工具响应的唯一标识符。

enum<string>

工具类型。目前仅支持 function。

可选值：function

object

显示子属性

string

工具名称。

string

输入参数信息，以 JSON 字符串格式表示。模型输出具有不确定性，调用函数前请先验证参数。

integer

当前工具在 tool_calls 数组中的索引。

integer

请求创建时的 Unix 时间戳（秒）。

string

本次请求使用的模型。

enum<string>

固定为 chat.completion。

可选值：chat.completion

string | null

目前固定为 null。

string | null

目前固定为 null。

object

本次请求的 Token 消耗明细。

显示子属性

integer

模型输出的 Token 数量。

integer

输入的 Token 数量。

integer

总消耗 Token 数量（prompt_tokens + completion_tokens）。

object

输出 Token 的细分明细。

显示子属性

integer | null

输出中的音频 Token 数量（Qwen-Omni）。

integer | null

思考过程中的 Token 数量。

integer

输出中的文本 Token 数量。

object

输入 Token 的细分明细。

显示子属性

integer | null

输入音频的 Token 数量。

integer

命中缓存的 Token 数量。

integer

输入中的文本 Token 数量。

integer

输入中的图片 Token 数量。

integer

输入视频的 Token 数量。

object

显式缓存创建的相关信息。

显示子属性

integer

创建显式缓存所消耗的 Token 数量。

integer

创建显式缓存所消耗的 Token 数量。

string

使用显式缓存时，值为 ephemeral；否则此字段不存在。