API详情

参数

数据类型

默认值

说明

model（必选）

string

无

指定用于对话的通义千问模型名，目前可选择 qwen-turbo 、 qwen-plus 、 qwen-max 、 qwen-max-0403 、 qwen-max-0107 、 qwen-max-1201 和 qwen-max-longcontext 。

messages

array

无

• messages ：用户与模型的对话历史。array中的每个元素形式为 {"role":角色, "content": 内容} ，角色当前可选值： system 、 user 、 assistant 和 tool 。

  • system ：表示系统级消息，用于指导模型按照预设的规范、角色或情境进行回应。是否使用 system 角色是可选的，如果使用则必须位于messages的最开始部分。

  • user 和 assistant ：表示用户和模型的消息。它们应交替出现在对话中，模拟实际对话流程。

  • tool ：表示工具的消息。在使用function call功能时，如果要传入工具的结果，需将元素的形式设为{"content":"工具返回的结果", "name":"工具的函数名", "role":"tool"}。其中name是工具函数的名称，需要和上轮response中的tool_calls[i]['function']['name']参数保持一致；content是工具函数的输出。 参考代码 给出了示例。

• prompt ：用户输入的指令，用于指导模型生成回复。

prompt

string

无（与messages不可同时为空）

seed（可选）

integer

生成时使用的随机数种子，用于控制模型生成内容的随机性。seed支持无符号64位整数。

max_tokens（可选）

integer

1500或2000

指定模型可生成的最大token个数。

• qwen-turbo 最大值和默认值为1500 tokens。

• qwen-max 、 qwen-max-1201 、 qwen-max-longcontext 和 qwen-plus 模型，最大值和默认值均为2000 tokens。

top_p（可选）

float

生成过程中的核采样方法概率阈值，例如，取值为0.8时，仅保留概率加起来大于等于0.8的最可能token的最小集合作为候选集。取值范围为（0,1.0)，取值越大，生成的随机性越高；取值越低，生成的确定性越高。

top_k（可选）

integer

生成时，采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。取值为None或当top_k大于100时，表示不启用top_k策略，此时，仅有top_p策略生效。

repetition_penalty（可选）

float

用于控制模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度，1.0表示不做惩罚。没有严格的取值范围。

presence_penalty（可选）

float

用户控制模型生成时整个序列中的重复度。提高presence_penalty时可以降低模型生成的重复度，取值范围[-2.0, 2.0]。

temperature（可选）

float

用于控制模型回复的随机性和多样性。具体来说，temperature值控制了生成文本时对每个候选词的概率分布进行平滑的程度。较高的temperature值会降低概率分布的峰值，使得更多的低概率词被选择，生成结果更加多样化；而较低的temperature值则会增强概率分布的峰值，使得高概率词更容易被选择，生成结果更加确定。

取值范围：[0, 2)，不建议取值为0，无意义。

stop (可选）

string or array

None

stop参数用于实现内容生成过程的精确控制，在模型生成的内容即将包含指定的字符串或token_id时自动停止。stop可以为string类型或array类型。

• string类型

  当模型将要生成指定的stop词语时停止。

  例如将stop指定为"你好"，则模型将要生成“你好”时停止。

• array类型

  array中的元素可以为token_id或者字符串，或者元素为token_id的array。当模型将要生成的token或其对应的token_id在stop中时，模型生成将会停止。以下为stop为array时的示例（tokenizer对应模型为qwen-turbo）：

  1.元素为token_id：

  token_id为108386和104307分别对应token为“你好”和“天气”，设定stop为 [108386,104307] ，则模型将要生成“你好”或者“天气”时停止。

  2.元素为字符串：

  设定stop为 ["你好","天气"] ，则模型将要生成“你好”或者“天气”时停止。

  3.元素为array：

  token_id为108386和103924分别对应token为“你好”和“啊”，token_id为35946和101243分别对应token为“我”和“很好”。设定stop为 [[108386, 103924],[35946, 101243]] ，则模型将要生成“你好啊”或者“我很好”时停止。

  说明

  stop为array类型时，不可以将token_id和字符串同时作为元素输入，比如不可以指定stop为 ["你好",104307] 。

stream (可选）

boolean

False

用于控制是否使用流式输出。当以stream模式输出结果时，接口返回结果为generator，需要通过迭代获取结果，默认每次输出为当前生成的整个序列，最后一次输出为最终全部生成结果，可以通过设置参数incremental_output为False改变输出模式为非增量输出。

enable_search（可选）

boolean

False

用于控制模型在生成文本时是否使用互联网搜索结果进行参考。取值如下：

• True：启用互联网搜索，模型会将搜索结果作为文本生成过程中的参考信息，但模型会基于其内部逻辑判断是否使用互联网搜索结果。

• False（默认）：关闭互联网搜索。

result_format（可选）

string

text

用于指定返回结果的格式，默认为text，也可选择message。当设置为message时，输出格式请参考 返回结果 。推荐您优先使用message格式。

incremental_output (可选）

boolean

False

控制在流式输出模式下是否开启增量输出，即后续输出内容是否包含已输出的内容。设置为True时，将开启增量输出模式，后面输出不会包含已经输出的内容，您需要自行拼接整体输出；设置为False则会包含已输出的内容。您可以参考 流式输出 代码。

默认False：

I

I like

I like apple

True:

I

like

apple

该参数只能在stream为True时使用。

tools

array

None

用于指定可供模型调用的工具库，一次function call流程模型会从中选择其中一个工具。tools中每一个tool的结构如下：

• type，类型为string，表示tools的类型，当前仅支持function。

• function，类型为object，键值包括name，description和parameters：

  • name：类型为string，表示工具函数的名称，必须是字母、数字，可以包含下划线和短划线，最大长度为64。

  • description：类型为string，表示工具函数的描述，供模型选择何时以及如何调用工具函数。

  • parameters：类型为object，表示工具的参数描述，需要是一个合法的JSON Schema。JSON Schema的描述可以见 链接 。 参考代码 中给出了参数描述的示例。如果parameters参数为空，表示function没有入参。

使用tools时需要同时指定result_format为message。在function call流程中，无论是发起function call的轮次，还是向模型提交工具函数的执行结果，均需设置tools参数。当前支持的模型包括qwen-turbo、qwen-plus、qwen-max和qwen-max-longcontext。

tool_choice

string or object

见说明

在使用tools参数时，用于控制模型调用指定工具。有四种取值：

• none表示不调用工具。tools参数为空时，默认值为none。

• auto表示模型判断是否调用工具，可能调用也可能不调用。tools参数不为空时，默认值为auto。

• object结构可以指定模型调用指定工具。例如 {"type": "function", "function": {"name": "user_function"}}

  • type现在只支持function

  • function

    • name表示期望被调用的工具名称

传参方式

字段

数据类型

必选

描述

示例值

Header

Content-Type

string

是

请求类型：application/json

"Content-Type":"application/json"

Accept

string

否

选择text/event-stream则会开启SSE响应，默认无设置。

"Accept":"text/event-stream"

Authorization

string

是

API-KEY，例如：Bearer d1**2a

"Authorization":"Bearer d1**2a"

X-DashScope-SSE

string

否

设置为enable或者设置Accept: text/event-stream即可启用SSE响应。

"X-DashScope-SSE":"enable"

Body

model

string

是

指定用于对话的通义千问模型名，目前可选择 qwen-turbo 、 qwen-plus 、 qwen-max 、 qwen-max-0403 、 qwen-max-0107 、 qwen-max-1201 和 qwen-max-longcontext 。

"model":"qwen-turbo"

input

object

是

输入模型的信息。

无

input.prompt

string

否

用户当前输入的期望模型执行指令，支持中英文。与input.messages指定其中一个即可。

"input":{"prompt":"你好"}

input.history

array

否

即将废弃，请使用messages字段 。 用户与模型的对话历史，array中的每个元素形式为{"user":"用户输入","bot":"模型输出"}的一轮对话，多轮对话按时间正序排列。

"input":{"history":[{"user":"今天天气好吗？",

"bot":"今天天气不错，要出去玩玩嘛？"},

{"user":"那你有什么地方推荐？",

"bot":"我建议你去公园，春天来了，花朵开了，很美丽。"}]}

input.messages

array

否

表示用户与模型的对话历史。array中的每个元素形式为 {"role":角色, "content": 内容} ，如果role为tool，元素形式为：

{"role":"tool","content":内容,"name":工具函数名}

角色可选值： system 、 user 、 assistant 和 tool 。

"input":{

"messages":[

{

"role": "system",

"content": "You are a helpful assistant."

},

{

"role": "user",

"content": "你好，附近哪里有博物馆？"

}]

}

input.messages.role

string

messages存在的时候不能省略。

input.messages.content

string

input.messages.name

string

input.messages.role为tool时不能省略

role为 tool 表示当前message为function_call的调用结果，name是工具函数名，需要和上轮response中的tool_calls[i].function.name参数保持一致，content为工具函数的输出。 参考代码 的多轮调用给出了示例。

parameters

object

否

用于控制模型生成的参数

无

parameters.result_format

string

否

用于指定返回结果的格式，默认为text，也可设置为message。当设置为message时，输出格式请参考 返回结果 。推荐优先使用message格式。

"parameters":{"result_format":"message"}

parameters.seed

integer

否

生成时使用的随机数种子，用户控制模型生成内容的随机性。seed支持无符号64位整数。在使用seed时，模型将尽可能生成相同或相似的结果，但目前不保证每次生成的结果完全相同。

"parameters":{"seed":666}

parameters.max_tokens

integer

否

用于限制模型生成token的数量，表示生成token个数的上限。其中qwen-turbo最大值和默认值为1500，qwen-max、qwen-max-1201 、qwen-max-longcontext 和 qwen-plus最大值和默认值均为2000。

"parameters":{"max_tokens":1500}

parameters.top_p

float

否

生成时，核采样方法的概率阈值。例如，取值为0.8时，仅保留累计概率之和大于等于0.8的概率分布中的token，作为随机采样的候选集。取值范围为（0,1.0)，取值越大，生成的随机性越高；取值越低，生成的随机性越低。注意，取值不要大于等于1。

"parameters":{"top_p":0.7}

parameters.top_k

integer

否

生成时，采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。注意：如果top_k参数为空或者top_k的值大于100，表示不启用top_k策略，此时仅有top_p策略生效。

"parameters":{"top_k":50}

parameters.repetition_penalty

float

否

用于控制模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度。1.0表示不做惩罚。没有严格的取值范围。

"parameters":{"repetition_penalty":1.0}

parameters.presence_penalty

float

否

用户控制模型生成时整个序列中的重复度。提高presence_penalty时可以降低模型生成的重复度，取值范围 [-2.0, 2.0]。

"parameters":{"presence_penalty":1.0}

parameters.temperature

float

否

用于控制随机性和多样性的程度。具体来说，temperature值控制了生成文本时对每个候选词的概率分布进行平滑的程度。较高的temperature值会降低概率分布的峰值，使得更多的低概率词被选择，生成结果更加多样化；而较低的temperature值则会增强概率分布的峰值，使得高概率词更容易被选择，生成结果更加确定。

取值范围：[0, 2)，不建议取值为0，无意义。

"parameters":{"temperature":0.85}

parameters.stop

string/array

否

stop参数用于实现内容生成过程的精确控制，在模型生成的内容即将包含指定的字符串或token_id时自动停止，生成的内容不包含指定的内容。stop可以为string类型或array类型。

• string类型

  当模型将要生成指定的stop词语时停止。

  例如将stop指定为"你好"，则模型将要生成“你好”时停止。

• array类型

  array中的元素可以为token_id或者字符串，或者元素为token_id的array。当模型将要生成的token或其对应的token_id在stop中时，模型生成将会停止。

  例如将stop指定为 ["你好","天气"] 或者 [108386,104307] ，则模型将要生成“你好”或者“天气”时停止。如果将stop指定为 [[108386, 103924],[35946, 101243]] ，则模型将要生成“你好啊”或者“我很好”时停止。

  说明

  stop为array类型时，不可以将token_id和字符串同时作为元素输入，比如不可以指定stop为 ["你好",104307] 。

"parameters":{"stop":["你好","天气"]}

parameters.enable_search

boolean

否

模型内置了互联网搜索服务，该参数控制模型在生成文本时是否参考使用互联网搜索结果。取值如下：

• true：启用互联网搜索，模型会将搜索结果作为文本生成过程中的参考信息，但模型会基于其内部逻辑“自行判断”是否使用互联网搜索结果。

• false（默认）：关闭互联网搜索。

"parameters":{"enable_search":false}

parameters.incremental_output

boolean

否

控制在流式输出模式下是否开启增量输出，即后续输出内容是否包含已输出的内容。设置为True时，将开启增量输出模式，后面输出不会包含已经输出的内容，您需要自行拼接整体输出；设置为False则会包含已输出的内容。

默认False：

I

I like

I like apple

True:

I

like

apple

该参数只能在开启SSE响应时使用。

"parameters":{"incremental_output":false}

parameters.tools

array

否

用于指定可供模型调用的工具列表。当输入多个工具时，模型会选择其中一个生成结果。tools中每一个tool的结构如下：

• type，类型为string，表示tools的类型，当前仅支持function。

• function，类型为object，键值包括name，description和parameters：

  • name：类型为string，表示工具函数的名称，必须是字母、数字，可以包含下划线和短划线，最大长度为64。

  • description：类型为string，表示工具函数的描述，供模型选择何时以及如何调用工具函数。

  • parameters：类型为object，表示工具的参数描述，需要是一个合法的JSON Schema。JSON Schema的描述可以见 链接 。 参考代码 中给出了一个参数描述的示例。如果parameters参数为空，表示function没有入参。

使用tools时需要同时指定result_format为message。在function call流程中，无论是发起function call的轮次，还是向模型提交工具函数的执行结果，均需设置tools参数。当前支持的模型包括qwen-turbo、qwen-plus、qwen-max和qwen-max-longcontext。

"parameters":{"tools":[
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    "unit": {
                        "type": "string",
                        "enum": [
                            "celsius",
                            "fahrenheit"
                "required": [
                    "location"
]}

parameters.tool_choice

string/object

否

在使用tools参数时，用于控制模型调用指定工具。有四种取值：

• none表示不调用工具。tools参数为空时，默认值为none。

• auto表示模型判断是否调用工具，可能调用也可能不调用。tools参数不为空时，默认值为auto。

• object结构可以指定模型调用指定工具。例如 {"type": "function", "function": {"name": "user_function"}}

  • type现在只支持function

  • function

    • name表示期望被调用的工具名称

{"type": "function", "function": {"name": "user_function"}}

字段

数据类型

描述

示例值

output.text

string

模型输出的内容。当result_format设置为text时返回该字段。

我建议你去颐和园

output.finish_reason

string

有三种情况：正在生成时为null，生成结束时如果由于停止token导致则为stop，生成结束时如果因为生成长度过长导致则为length。当result_format设置为text时返回该字段。

stop

output.choices

array

当result_format设置为message时返回该字段。

• 普通示例

  {
      "choices": [
              "finish_reason": "null",
              "message": {
                  "role": "assistant",
                  "content": "周围的咖啡馆在..."
  }

• function call示例

  {
      "choices": [
              "finish_reason": "tool_calls",
              "message": {
                  "role": "assistant",
                  "content": "",
                  "tool_calls": [
                          "function": {
                              "name": "get_current_weather",
                              "arguments": "{\"location\": \"Boston\", \"unit\": \"fahrenheit\"}"
                          "type": "function"
  }

output.choices[x].finish_reason

string

停止原因，null：生成过程中

stop：stop token导致结束

length：生成长度导致结束

output.choices[x].message

object

message每个元素形式为{"role":角色, "content": 内容}。角色可选值： system 、 user 、 assistant 。content为模型输出的内容。

output.choices[x].message.role

string

output.choices[x].message.content

string

output.choices[x].message.tool_calls

object

如果模型需要调用工具，则会生成tool_calls参数，应用于function_call场景。其中包含type和function两个参数， 返回结果 中给出了function_call的示例。参数详情如下：：

• type，类型为string，当前只可能为function

• function，类型为dict，包含name和arguments两个参数：

  • name，类型为string，表示需要调用的工具的名称，如果是function_call场景则表示要调用的function名称

  • arguments，类型为string，表示模型生成的工具入参，在Python中可以使用json.loads方法转化为字典类型。

usage

object

本次调用使用的token信息。

无

usage.output_tokens

integer

模型输出内容的 token个数。

380

usage.input_tokens

integer

本次请求输入内容的token个数。在enable_search设置为true时，输入的 token 数目由于需要添加搜索相关内容，因此会比您在请求中的输入token个数多。

633

usage.total_tokens

integer

usage.output_tokens与usage.input_tokens的总和。

1013

request_id

string

本次请求的系统唯一码。

7574ee8f-38a3-4b1e-9280-11c33ab46e51