DashScope API 参考

POST

/api/v1/services/aigc/text-generation/generation

import os
import dashscope

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'
messages = [
  {'role': 'system', 'content': 'You are a helpful assistant.'},
  {'role': 'user', 'content': 'Who are you?'}
]
response = dashscope.Generation.call(
  api_key=os.getenv('DASHSCOPE_API_KEY'),
  model='qwen-plus',
  messages=messages,
  result_format='message'
)
print(response)

{
  "status_code": 200,
  "request_id": "902fee3b-f7f0-9a8c-96a1-6b4ea25af114",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "I am a large-scale language model developed by Alibaba Cloud. My name is Qwen.",
          "tool_calls": null,
          "reasoning_content": null
        }
      }
    ]
  },
  "usage": {
    "input_tokens": 22,
    "output_tokens": 17,
    "total_tokens": 39,
    "image_tokens": null,
    "video_tokens": null,
    "audio_tokens": null
  }
}

获取 API Key 并将其设置为环境变量。如需使用 SDK，请先安装 SDK。

接口地址

HTTP（纯文本模型，如 qwen-plus）：POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation
HTTP（多模态模型，如 qwen3.6-plus、qwen3-vl-plus）：POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
SDK base_http_api_url：https://dashscope.aliyuncs.com/api/v1

Python SDK：

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

Java SDK：

// 方式一：实例化时指定
import com.alibaba.dashscope.protocol.Protocol;
Generation gen = new Generation(Protocol.HTTP.getValue(), "https://dashscope.aliyuncs.com/api/v1");

// 方式二：全局设置
import com.alibaba.dashscope.utils.Constants;
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";

鉴权

string

header

必填

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

请求体

application/json

string

必填

调用的模型名称。支持 Qwen 大语言模型（商业版和开源版）、Qwen-Coder、数学模型、DeepSeek（阿里云直供、硅基流动直供）、Kimi（阿里云直供）、GLM（阿里云直供）、MiniMax（阿里云直供、稀宇科技直供）。模型列表详见文本生成 — Qwen。

示例:qwen-plus

object

必填

模型的输入。

显示子属性

(系统消息 · object | 用户消息 · object | 助手消息 · object | 工具消息 · object)[]

必填

对话上下文，以有序的消息列表形式提供。每条消息为 system、user、assistant 或 tool 消息对象。

设置模型的角色、语气、任务目标或约束条件。通常放在 messages 数组的首位。QwQ 模型请勿设置此消息。QVQ 模型设置后不生效。

系统消息
用户消息
助手消息
工具消息

显示子属性

enum<string>

必填

固定为 system。

可选值：system

string

必填

为模型设定上下文的系统消息内容。

object

文本模型的可选生成参数。

显示子属性

enum<string>

默认值"text"

返回数据的格式。多轮对话时请设为 message。

**默认值：**大多数模型默认为 text，但 Qwen3-Max、Qwen3-VL、QwQ 和 Qwen3 开源模型（qwen3-next-80b-a3b-instruct 除外）默认为 message。

使用 Qwen-VL/QVQ 模型时，设为 text 不生效。Qwen3-Max、Qwen3-VL 和 Qwen3 模型在思考模式下只能设为 message。

可选值：message,text

number

采样温度。控制输出的多样性。较高的值使输出更多样化，较低的值使输出更确定。取值范围：[0, 2)。

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
Kimi 系列（阿里云直供）：kimi-k2.6（思考模式）、kimi-k2.5（思考模式）、kimi-k2-thinking: 1.0；kimi-k2.6（非思考模式）、kimi-k2.5（非思考模式）、Moonshot-Kimi-K2-Instruct: 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.5、MiniMax/MiniMax-M2.1: 1.0

取值范围：0 <= x < 2

number

核采样阈值。较高的值使输出更多样化。取值范围：(0, 1.0]。

各模型默认值：

Qwen3.5（非思考模式）、Qwen3（非思考模式）、Qwen3-Instruct 系列、Qwen3-Coder 系列、qwen-max 系列、qwen-plus 系列（非思考模式）、qwen-flash 系列（非思考模式）、qwen-turbo 系列（非思考模式）、qwen 开源系列、qwen-vl-max-2025-08-13、Qwen3-VL（非思考模式）：0.8
qwen-vl-plus 系列、qwen-vl-max、qwen-vl-max-latest、qwen-vl-max-2025-04-08、qwen2.5-vl-3b/7b/32b/72b-instruct：0.001
QVQ 系列、qwen-vl-plus-2025-07-10、qwen-vl-plus-2025-08-15：0.5
qwen3-max-preview（思考模式）、Qwen3-Omni-Flash 系列：1.0
Qwen3.5（思考模式）、Qwen3（思考模式）、Qwen3-VL（思考模式）、Qwen3-Thinking、QwQ 系列、Qwen3-Omni-Captioner：0.95
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 系列（硅基流动直供）：1.0
Kimi 系列（阿里云直供）：kimi-k2.6、kimi-k2.5、kimi-k2-thinking: 0.95；Moonshot-Kimi-K2-Instruct: 1.0
GLM 系列（阿里云直供）：0.95
MiniMax 系列（阿里云直供）：MiniMax-M2.5、MiniMax-M2.1: 0.95
MiniMax 系列（稀宇科技直供）：MiniMax/MiniMax-M2.5、MiniMax/MiniMax-M2.1: 0.9

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

取值范围：0 < x <= 1

integer

采样候选 token 集合的大小。较大的值增加随机性，较小的值增加确定性。如果为 None 或大于 100，则 top_k 不生效，仅 top_p 起作用。必须 >= 0。

各模型默认值：

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

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

取值范围：x >= 0

integer

生成的最大 token 数。达到限制时，生成停止且 finish_reason 为 length。不限制思考链长度。默认为模型的最大输出长度。

boolean

默认值false

是否流式输出响应。HTTP 流式输出还需设置 X-DashScope-SSE: enable 请求头。Java SDK 流式输出请使用 streamCall 接口。

boolean

默认值false

流式输出时，是否仅返回新增的增量 token（true）还是返回到目前为止的完整累积文本（false）。

boolean

是否启用思考模式。适用于混合思考模型：Qwen3.6、Qwen3.5、Qwen3 和 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 字段返回。Java SDK 为 enableThinking；通过 HTTP 调用时，请将 enable_thinking 放入 parameters 对象中。

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 数量并计费。

通过 HTTP 调用时，请将 preserve_thinking 放入 parameters 对象中。暂不支持 Java SDK。

integer

思考链的最大长度。适用于 Qwen3.6、Qwen3.5、Qwen3-VL 和 Qwen3 的商业版和开源版。默认为模型的最大思维链长度。Java SDK 为 thinkingBudget。通过 HTTP 调用时，请将 thinking_budget 放入 parameters 对象中。

enum<string>

默认值"high"

控制 DeepSeek-V4 系列模型的推理力度。可选值：high（高力度推理）、max（最大力度推理）。low 和 medium 映射为 high，xhigh 映射为 max。适用于 deepseek-v4-pro、deepseek-v4-flash（阿里云直供）。通过 HTTP 调用时，请将 reasoning_effort 放入 parameters 对象中。

可选值：high,max

boolean

默认值false

开启后，Function Calling 的 tool_call arguments 以流式增量方式返回，而非一次性返回。仅在流式调用时生效。适用于 glm-5.1、glm-5、glm-4.7、glm-4.6（阿里云直供）。通过 HTTP 调用时，请将 tool_stream 放入 parameters 对象中。

boolean

默认值false

是否启用代码解释器功能。仅 qwen3.5、qwen3-max、qwen3-max-2026-01-23 和 qwen3-max-preview 在思考模式下支持。

number

token 重复惩罚系数。1.0 表示不惩罚，较高的值减少重复。必须为正数。

第三方模型默认值：

DeepSeek 系列（阿里云直供）：deepseek-v3.2-exp/v3.1: 1.0
GLM 系列（阿里云直供）：1.0

使用 qwen-vl-plus_2025-01-25 模型进行文字识别时，请将 repetition_penalty 设为 1.0。QVQ 模型请勿修改默认 repetition_penalty 值。

number

控制模型避免重复文本中已有内容的程度。取值范围：[-2.0, 2.0]。正值减少重复，负值增加重复。

各模型默认值：

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
所有其他模型：0.0

使用 qwen-vl-plus-2025-01-25 进行文字识别时，请将 presence_penalty 设为 1.5。QVQ 模型请勿修改默认值。

取值范围：-2 <= x <= 2

integer

随机种子，用于结果复现。取值范围：[0, 2³¹−1]。使用相同的种子和参数时，模型会尽可能返回相同的结果。

取值范围：x >= 0

string

停止序列。当生成的文本包含指定的字符串或 token ID 时，生成立即停止。同一数组中不要混用字符串和 token ID。并非所有模型都支持，请查看模型文档。

object[]

用于函数调用的工具对象数组。使用工具时，必须将 result_format 设为 message。不支持 qwen-vl 系列模型。使用示例详见函数调用指南。

显示子属性

enum<string>

必填

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

可选值：function

object

必填

显示子属性

string

必填

工具函数的名称。可包含字母、数字、下划线和连字符。最长 64 个字符。

string

必填

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

object

描述函数参数的 JSON Schema 对象。默认为 {}。

enum<string>

默认值"auto"

定义工具选择策略。思考模式的模型不支持强制指定工具。

boolean

默认值false

是否启用并行工具调用。思考模式的模型在强制指定工具时不支持此功能。详见并行工具调用。

object

默认值{"type":"text"}

返回内容的格式。设为 json_object 时，必须在提示词中指示模型输出 JSON。

显示子属性

enum<string>

输出格式类型。text：纯文本。json_object：标准 JSON 字符串。json_schema：符合指定 schema 的 JSON。

可选值：text,json_object,json_schema

object

当 type 为 json_schema 时必填。定义结构化输出的 JSON Schema。支持的模型详见结构化输出。

显示子属性

string

唯一的 schema 名称（字母、数字、下划线、连字符；最长 64 个字符）。

string

schema 用途的描述。

object

定义输出数据结构的 JSON Schema 对象。

boolean

默认值false

模型是否必须严格遵守所有 schema 约束。建议设为 true。

boolean

默认值false

是否返回输出 token 的对数概率。支持的模型：qwen-plus/qwen-turbo 系列的快照模型、qwen3-vl-plus/qwen3-vl-flash 系列、Qwen3 开源模型。具体支持的模型请查看模型页面。

integer

默认值0

每个生成步骤返回的最可能候选 token 数。有效值：0–5。仅在 logprobs 为 true 时生效。支持的模型与 logprobs 相同。

取值范围：0 <= x <= 5

integer

默认值1

生成的响应数量。范围：1–4。目前仅支持非思考模式的 Qwen3 模型。指定 tools 时固定为 1。会增加输出 token 消耗。

取值范围：1 <= x <= 4

boolean

默认值false

是否启用高分辨率图像处理。启用后使用固定分辨率策略，max_pixels 被忽略。默认值：false。

启用时（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：固定为 16777216 像素（16384 个 token × 32×32 像素）
QVQ 系列和其他 Qwen2.5-VL 系列：固定为 12845056 像素（16384 个 token × 28×28 像素）

为 false 时，像素限制由 max_pixels 决定。

boolean

默认值false

是否在响应中返回缩放后图像的尺寸（image_hw 字段）。流式输出时在最后一个数据块中返回。适用于 Qwen-VL 系列模型。

响应

200-application/json

integer

请求的状态码。200 表示成功。Java SDK 不返回此字段；调用失败时会抛出包含 status_code 的异常。

string

此请求的唯一标识符。在 Java SDK 中为 requestId。

string

错误码。请求成功时为空字符串。仅 Python SDK 返回此字段。

string

可读的错误信息。请求成功时为空字符串。

object

模型的输出。

显示子属性

string | null

生成的文本。当 result_format 为 text 时返回。

string | null

生成停止的原因。当 result_format 为 text 时返回。取值：null（仍在生成中）、stop（自然结束或触发停止条件）、length（达到最大 token 数）、tool_calls（触发工具调用）。

object[]

输出选项。当 result_format 为 message 时返回。

显示子属性

string | null

生成停止的原因。取值：null（生成中）、stop、length、tool_calls。

object

助手的输出消息。

显示子属性

string

固定为 assistant。

string

消息内容。文本模型为字符串；Qwen-VL/Qwen-Audio 模型为数组。存在 tool_calls 时为空。

string | null

深度思考内容。启用思考模式时返回。

object[] | null

模型请求的工具调用。当模型触发函数调用时返回。

显示子属性

string

工具调用的 ID。

enum<string>

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

可选值：function

object

显示子属性

string

工具函数的名称。

string

工具的输入参数，为 JSON 字符串。

integer

此工具调用在 tool_calls 数组中的索引。

object | null

此选项的对数概率信息。当 logprobs 为 true 时返回。

显示子属性

object[]

包含对数概率信息的 token 数组。

显示子属性

string

integer[]

number | null

object[]

显示子属性

string

integer[]

number | null

object

此请求的 token 用量信息。

显示子属性

integer

用户输入的 token 数。

integer

模型输出的 token 数。

integer

总 token 数（输入 + 输出）。纯文本输入时返回。

integer | null

输入图像的 token 数。输入包含图像时返回。

integer | null

输入视频的 token 数。输入包含视频时返回。

integer | null

输入音频的 token 数。输入包含音频时返回。

object

Qwen-VL 和 QVQ 模型的输入 token 明细。

显示子属性

integer

object

输出 token 明细。

显示子属性

integer

输出文本的 token 数。

integer

思考过程的 token 数。

object

输入 token 的细粒度分类。

显示子属性

integer

命中缓存的 token 数。详见上下文缓存。

integer

用于创建显式缓存的 token 数。

string

使用显式缓存时，值为 ephemeral。否则不返回。

object

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

显示子属性

integer

用于创建 5 分钟显式缓存的 token 数。

​接口地址

鉴权

请求体

响应

接口地址