Skip to main content
更多模型

GUI-Plus API参考

本文介绍通过 OpenAI 兼容接口 或 DashScope API 调用GUI-Plus模型的输入与输出参数。

相关文档:界面交互专用模型(GUI-Plus)

OpenAI 兼容

SDK 调用配置的base_url为:https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 HTTP 调用配置的endpointPOST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions
阿里云百炼为华北2(北京)、新加坡地域推出了业务空间专属域名,能够为推理请求提供卓越的性能和更高的稳定性,建议迁移至新域名:
  • 华北2(北京)地域:从 https://dashscope.aliyuncs.com 迁移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地域:从 https://dashscope-intl.aliyuncs.com 迁移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
其中 {WorkspaceId} 为您的业务空间 ID,可在阿里云百炼控制台的业务空间详情页面查看。现有域名仍可正常使用。
您需要已获取与配置 API Key配置API Key到环境变量。若通过OpenAI SDK进行调用,需要安装SDK

请求体

modelstring(必选)模型名称。支持的模型:gui-plus。messagesarray(必选)传递给大模型的上下文,按对话顺序排列。
System Messageobject(可选)系统消息,用于设定大模型的角色、语气、任务目标或约束条件等。一般放在messages数组的第一位。
contentstring(必选)系统指令,用于明确模型的角色、行为规范、回答风格和任务约束等。rolestring(必选)系统消息的角色,固定为system
User Messageobject(必选)用户消息。
contentarray(必选)消息内容。
typestring(必选)可选值:
  • text 输入文本时需设为text
  • image_url 输入图片时需设为image_url
textstring(可选)输入的文本。当typetext时,是必选参数。image_urlobject输入的图片信息。当typeimage_url时是必选参数。
url string(必选)图片的 URL或 Base64 Data URL。传入本地文件请参考传入本地文件
min_pixelsinteger(可选)用于设定输入图像的最小像素阈值,单位为像素。当输入图像像素小于min_pixels时,会将图像进行放大,直到总像素高于min_pixels默认值和最小值均为 3136 。max_pixelsinteger(可选)用于设定输入图像的最大像素阈值,单位为像素。当输入图像像素在[min_pixels, max_pixels]区间内时,模型会按原图进行识别。当输入图像像素大于max_pixels时,会将图像进行缩小,直到总像素低于max_pixels默认值和最大值和vl_high_resolution_images的取值有关:
rolestring(必选)用户消息的角色,固定为user
Assistant Message object(可选)模型的回复。通常用于在多轮对话中作为上下文回传给模型。
contentstring(必选)模型回复的文本内容。rolestring(必选)助手消息的角色,固定为assistant
streamboolean(可选) 默认值为 false是否以流式方式输出回复。可选值:
  • false:等待模型生成完整回复后一次性返回。
  • true:模型边生成边返回数据块。客户端需逐块读取,以还原完整回复。
stream_optionsobject(可选)流式输出的配置项,仅在 streamtrue 时生效。

属性

include_usageboolean(可选)默认值为 false是否在最后一个数据块包含Token消耗信息。可选值:
  • true:包含;
  • false:不包含。
max_tokensinteger(可选)用于限制模型输出的最大 Token 数。若生成内容超过此值,响应将被截断。默认值与最大值均为模型的最大输出长度,请参见模型选型vl_high_resolution_imagesboolean(可选)默认值为false是否将输入图像的像素上限提升至 16384 Token 对应的像素值。
  • vl_high_resolution_images为true,使用固定分辨率策略,像素上限固定为12845056,忽略 max_pixels 设置,超过此分辨率时会将图像总像素缩小至此上限内。
  • vl_high_resolution_imagesfalse,像素上限由max_pixels决定,输入图像的像素超过max_pixels会将图像缩小至max_pixels内。模型的默认像素上限即max_pixels的默认值。
enable_thinking boolean (可选)使用混合思考(回复前既可思考也可不思考)模型时,是否开启思考模式。在界面交互系列模型中,仅gui-plus-2026-02-26为混合思考模型。相关文档:视觉推理可选值:
  • true:开启
    开启后,思考内容将通过reasoning_content字段返回。
  • false:不开启
该参数非OpenAI标准参数。通过 Python SDK调用时,请放入 extra_body 对象中。配置方式为:extra_body={"enable_thinking": xxx}
seedinteger(可选)随机数种子。用于确保在相同输入和参数下生成结果可复现。若调用时传入相同的 seed 且其他参数不变,模型将尽可能返回相同结果。取值范围:[0,2 31 −1]temperaturefloat(可选)默认值为0.01采样温度,控制模型生成文本的多样性。temperature越高,生成的文本更多样,反之,生成的文本更确定。取值范围: [0, 2)temperature与top_p均可以控制生成文本的多样性,建议只设置其中一个值。top_pfloat(可选)默认值为0.01核采样的概率阈值,控制模型生成文本的多样性。top_p越高,生成的文本更多样。反之,生成的文本更确定。取值范围:(0,1.0]temperature与top_p均可以控制生成文本的多样性,建议只设置其中一个值。top_kinteger(可选)默认值为1生成过程中采样候选集的大小。例如,取值为50时,仅将单次生成中得分最高的50个Token组成随机采样的候选集。取值越大,生成的随机性越高;取值越小,生成的确定性越高。取值为None或当top_k大于100时,表示不启用top_k策略,此时仅有top_p策略生效。取值需要大于或等于0。该参数非OpenAI标准参数。通过 Python SDK调用时,请放入 extra_body 对象中,配置方式为:extra_body={"top_k": xxx};通过 Node.js SDK 或 HTTP 方式调用时,请作为顶层参数传递。repetition_penaltyfloat(可选)默认值为1.0模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度,1.0表示不做惩罚。该参数对模型效果影响较大,建议保持默认值。presence_penalty float(可选)控制模型生成文本时的内容重复度。默认值为1.5取值范围:[-2.0, 2.0]。正值降低重复度,负值增加重复度。在创意写作或头脑风暴等需要多样性、趣味性或创造力的场景中,建议调高该值;在技术文档或正式文本等强调一致性与术语准确性的场景中,建议调低该值。
如果参数值是正数,模型将对目前文本中已存在的Token施加一个惩罚值(惩罚值与文本出现的次数无关),减少这些Token重复出现的几率,从而减少内容重复度,增加用词多样性。
提示词:把这句话翻译成中文“This movie is good. The plot is good, the acting is good, the music is good, and overall, the whole movie is just good. It is really good, in fact. The plot is so good, and the acting is so good, and the music is so good.”参数值为2.0:这部电影很好。剧情很棒,演技棒,音乐也非常好听,总的来说,整部电影都好得不得了。实际上它真的很优秀。剧情非常精彩,演技出色,音乐也是那么的动听。参数值为0.0:这部电影很好。剧情好,演技好,音乐也好,总的来说,整部电影都很好。事实上,它真的很棒。剧情非常好,演技也非常出色,音乐也同样优秀。参数值为-2.0:这部电影很好。情节很好,演技很好,音乐也很好,总的来说,整部电影都很好。实际上,它真的很棒。情节非常好,演技也非常好,音乐也非常好。
stopstring 或 array(可选)用于指定停止词。当模型生成的文本中出现stop 指定的字符串或token_id时,生成将立即终止。可传入敏感词以控制模型的输出。
stop为数组时,不可将token_id和字符串同时作为元素输入,比如不可以指定为["你好",104307]
  • 非流式输出
  • 流式输出
  • Python
  • Node.js
  • curl
import os
from openai import OpenAI

system_prompt = """# Tools

You may call one or more functions to assist with the user query.

You are provided with function signatures within <tools></tools> XML tags:
<tools>
{"type": "function", "function": {"name": "computer_use", "description": "Use a mouse and keyboard to interact with a computer, and take screenshots.\\n* This is an interface to a desktop GUI. You do not have access to a terminal or applications menu. You must click on desktop icons to start applications.\\n* Some applications may take time to start or process actions, so you may need to wait and take successive screenshots to see the results of your actions. E.g. if you click on Firefox and a window doesn't open, try wait and taking another screenshot.\\n* The screen's resolution is 1000x1000.\\n* Make sure to click any buttons, links, icons, etc with the cursor tip in the center of the element. Don't click boxes on their edges unless asked.", "parameters": {"properties": {"action": {"description": "The action to perform. The available actions are:\\n* `key`: Performs key down presses on the arguments passed in order, then performs key releases in reverse order.\\n* `type`: Type a string of text on the keyboard.\\n* `mouse_move`: Move the cursor to a specified (x, y) pixel coordinate on the screen.\\n* `left_click`: Click the left mouse button at a specified (x, y) pixel coordinate on the screen.\\n* `left_click_drag`: Click and drag the cursor to a specified (x, y) pixel coordinate on the screen.\\n* `right_click`: Click the right mouse button at a specified (x, y) pixel coordinate on the screen.\\n* `middle_click`: Click the middle mouse button at a specified (x, y) pixel coordinate on the screen.\\n* `double_click`: Double-click the left mouse button at a specified (x, y) pixel coordinate on the screen.\\n* `triple_click`: Triple-click the left mouse button at a specified (x, y) pixel coordinate on the screen (simulated as double-click since it's the closest action).\\n* `scroll`: Performs a scroll of the mouse scroll wheel.\\n* `hscroll`: Performs a horizontal scroll (mapped to regular scroll).\\n* `wait`: Wait specified seconds for the change to happen.\\n* `terminate`: Terminate the current task and report its completion status.\\n* `answer`: Answer a question.\\n* `interact`: Resolve the blocking window by interacting with the user.", "enum": ["key", "type", "mouse_move", "left_click", "left_click_drag", "right_click", "middle_click", "double_click", "triple_click", "scroll", "hscroll", "wait", "terminate", "answer", "interact"], "type": "string"}, "keys": {"description": "Required only by `action=key`.", "type": "array"}, "text": {"description": "Required only by `action=type`, `action=answer` and `action=interact`.", "type": "string"}, "coordinate": {"description": "(x, y): The x (pixels from the left edge) and y (pixels from the top edge) coordinates to move the mouse to. Required only by `action=mouse_move` and `action=left_click_drag`.", "type": "array"}, "pixels": {"description": "The amount of scrolling to perform. Positive values scroll up, negative values scroll down. Required only by `action=scroll` and `action=hscroll`.", "type": "number"}, "time": {"description": "The seconds to wait. Required only by `action=wait`.", "type": "number"}, "status": {"description": "The status of the task. Required only by `action=terminate`.", "type": "string", "enum": ["success", "failure"]}}, "required": ["action"], "type": "object"}}}
</tools>

For each function call, return a json object with function name and arguments within <tool_call></tool_call> XML tags:
<tool_call>
{"name": <function-name>, "arguments": <args-json-object>}
</tool_call>

# Response format

Response format for every step:
1) Action: a short imperative describing what to do in the UI.
2) A single <tool_call>...</tool_call> block containing only the JSON: {"name": <function-name>, "arguments": <args-json-object>}.

Rules:
- Output exactly in the order: Action, <tool_call>.
- Be brief: one for Action.
- Do not output anything else outside those two parts.
- If finishing, use action=terminate in the tool call."""

messages = [
    {
        "role": "system",
        "content": system_prompt
    },
    {
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "https://img.alicdn.com/imgextra/i2/O1CN016iJ8ob1C3xP1s2M6z_!!6000000000026-2-tps-3008-1758.png"}},
            {"type": "text", "text": "帮我打开浏览器"}
        ]
    }
]

client = OpenAI(
    # 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="gui-plus-2026-02-26",
    messages=messages,
    extra_body={"vl_high_resolution_images": True}
)

print(completion.choices[0].message.content)

chat响应对象(非流式输出)

idstring本次请求的唯一标识符。choicesarray模型生成内容的数组。

属性

finish_reasonstring模型停止生成的原因。有两种情况:
  • 自然停止输出时为stop
  • 生成长度过长而结束为length
indexinteger当前对象在choices数组中的索引。messageobject模型输出的消息。

属性

content stringGUI任务的结果。refusal string该参数当前固定为nullrole string消息的角色,固定为assistantaudio object该参数当前固定为nullfunction_call object该参数当前固定为nulltool_calls array该参数当前固定为null
createdinteger本次请求被创建时的时间戳。modelstring本次请求使用的模型。object string始终为chat.completionservice_tier string该参数当前固定为nullsystem_fingerprintstring该参数当前固定为nullusage object本次请求的 Token 消耗信息。
completion_tokens integer模型输出的 Token 数。prompt_tokens integer输入的 Token 数。total_tokens integer消耗的总 Token 数,为prompt_tokenscompletion_tokens的总和。completion_tokens_details object模型输出Token的细粒度分类。
accepted_prediction_tokensinteger该参数当前固定为nullaudio_tokens integer该参数当前固定为nullreasoning_tokens integer该参数当前固定为nulltext_tokens integer模型输出文本对应的 Token 数。rejected_prediction_tokensinteger该参数当前固定为null
prompt_tokens_details object输入 Token 的细粒度分类。
audio_tokens integer该参数当前固定为nullcached_tokens integer该参数当前固定为nulltext_tokens integer模型输入的文本对应的Token 数。image_tokens integer模型输入的图像对应的 Token数。
{
  "id": "chatcmpl-ef17511a-aceb-4c47-8757-13a87af2152d",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "```json\n{\"thought\": \"用户想要打开浏览器,我观察到屏幕截图中有一个Google Chrome的图标,其位置在右上角一排的最后一个。因此,下一步操作应该是点击这个Chrome浏览器图标来启动它。\", \"action\": \"click\", \"parameters\": {\"x\": 1086, \"y\": 129}}\n```",
        "refusal": null,
        "role": "assistant",
        "annotations": null,
        "audio": null,
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1763451557,
  "model": "gui-plus",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 78,
    "prompt_tokens": 2020,
    "total_tokens": 2098,
    "completion_tokens_details": {
      "accepted_prediction_tokens": null,
      "audio_tokens": null,
      "reasoning_tokens": null,
      "rejected_prediction_tokens": null,
      "text_tokens": 78
    },
    "prompt_tokens_details": {
      "audio_tokens": null,
      "cached_tokens": null,
      "image_tokens": 1244,
      "text_tokens": 776
    }
  }
}

chat响应chunk对象(流式输出)

idstring本次调用的唯一标识符。每个chunk对象有相同的 id。choicesarray模型生成内容的数组。若设置include_usage参数为true,则在最后一个chunk中为空。

属性

delta object流式返回的输出内容。

属性

content string翻译结果,qwen-mt-flash为增量式更新,qwen-mt-plus和qwen-mt-turbo为非增量式更新。function_call object该参数当前固定为nullrefusal object该参数当前固定为nullrole string消息对象的角色,只在第一个chunk中有值。
finish_reason string模型停止生成的原因。有三种情况:
  • 自然停止输出时为stop
  • 生成未结束时为null
  • 生成长度过长而结束为length
index integer当前响应在choices数组中的索引。
createdinteger本次请求被创建时的时间戳。每个chunk有相同的时间戳。modelstring本次请求使用的模型。object string始终为chat.completion.chunkservice_tier string该参数当前固定为nullsystem_fingerprintstring该参数当前固定为nullusage object本次请求消耗的Token。只在include_usagetrue时,在最后一个chunk返回。
completion_tokens integer模型输出的 Token 数。prompt_tokens integer输入的 Token 数。total_tokens integer消耗的总 Token 数,为prompt_tokenscompletion_tokens的总和。completion_tokens_details object模型输出Token的细粒度分类。
accepted_prediction_tokensinteger该参数当前固定为nullaudio_tokens integer该参数当前固定为nullreasoning_tokens integer该参数当前固定为nulltext_tokens integer模型输出文本对应的 Token 数。rejected_prediction_tokensinteger该参数当前固定为null
prompt_tokens_details object输入 Token 的细粒度分类。
audio_tokens integer该参数当前固定为nullcached_tokens integer该参数当前固定为nulltext_tokens integer模型输入的文本对应的Token 数。image_tokens integer模型输入的图像对应的 Token数。
ChatCompletionChunk(id='chatcmpl-9f3c627a-b0fc-4160-a558-3cc2cc7aa988', choices=[Choice(delta=ChoiceDelta(content='', function_call=None, refusal=None, role='assistant', tool_calls=None), finish_reason=None, index=0, logprobs=None)], created=1763452343, model='gui-plus', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None)
ChatCompletionChunk(id='chatcmpl-9f3c627a-b0fc-4160-a558-3cc2cc7aa988', choices=[Choice(delta=ChoiceDelta(content='```', function_call=None, refusal=None, role=None, tool_calls=None), finish_reason=None, index=0, logprobs=None)], created=1763452343, model='gui-plus', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None)
ChatCompletionChunk(id='chatcmpl-9f3c627a-b0fc-4160-a558-3cc2cc7aa988', choices=[Choice(delta=ChoiceDelta(content='json', function_call=None, refusal=None, role=None, tool_calls=None), finish_reason=None, index=0, logprobs=None)], created=1763452343, model='gui-plus', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None)
ChatCompletionChunk(id='chatcmpl-9f3c627a-b0fc-4160-a558-3cc2cc7aa988', choices=[Choice(delta=ChoiceDelta(content=None, function_call=None, refusal=None, role=None, tool_calls=None), finish_reason=None, index=0, logprobs=None)], created=1763452343, model='gui-plus', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None)
ChatCompletionChunk(id='chatcmpl-9f3c627a-b0fc-4160-a558-3cc2cc7aa988', choices=[Choice(delta=ChoiceDelta(content='\n{"thought": "', function_call=None, refusal=None, role=None, tool_calls=None), finish_reason=None, index=0, logprobs=None)], created=1763452343, model='gui-plus', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None)
...
ChatCompletionChunk(id='chatcmpl-9f3c627a-b0fc-4160-a558-3cc2cc7aa988', choices=[Choice(delta=ChoiceDelta(content=' 1086', function_call=None, refusal=None, role=None, tool_calls=None), finish_reason=None, index=0, logprobs=None)], created=1763452343, model='gui-plus', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None)
ChatCompletionChunk(id='chatcmpl-9f3c627a-b0fc-4160-a558-3cc2cc7aa988', choices=[Choice(delta=ChoiceDelta(content=', "y":', function_call=None, refusal=None, role=None, tool_calls=None), finish_reason=None, index=0, logprobs=None)], created=1763452343, model='gui-plus', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None)
ChatCompletionChunk(id='chatcmpl-9f3c627a-b0fc-4160-a558-3cc2cc7aa988', choices=[Choice(delta=ChoiceDelta(content=' 127', function_call=None, refusal=None, role=None, tool_calls=None), finish_reason=None, index=0, logprobs=None)], created=1763452343, model='gui-plus', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None)
ChatCompletionChunk(id='chatcmpl-9f3c627a-b0fc-4160-a558-3cc2cc7aa988', choices=[Choice(delta=ChoiceDelta(content='}}\n```', function_call=None, refusal=None, role=None, tool_calls=None), finish_reason='stop', index=0, logprobs=None)], created=1763452343, model='gui-plus', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=None)
ChatCompletionChunk(id='chatcmpl-bdb03054-42a2-459b-8a7e-5b94b39626f2', choices=[], created=1763452463, model='gui-plus', object='chat.completion.chunk', service_tier=None, system_fingerprint=None, usage=CompletionUsage(completion_tokens=78, prompt_tokens=2020, total_tokens=2098, completion_tokens_details=CompletionTokensDetails(accepted_prediction_tokens=None, audio_tokens=None, reasoning_tokens=None, rejected_prediction_tokens=None, text_tokens=78), prompt_tokens_details=PromptTokensDetails(audio_tokens=None, cached_tokens=None, image_tokens=1244, text_tokens=776)))

DashScope

  • HTTP 请求地址:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
  • SDK 调用:无需配置 base_url
您需要已获取与配置 API Key配置API Key到环境变量。若通过DashScope SDK进行调用,需要安装DashScope SDK

请求体

modelstring(必选)模型名称。支持的模型:gui-plus。messagesarray(必选)传递给大模型的上下文,按对话顺序排列。
通过HTTP调用时,请将messages放入 input 对象中。
System Messageobject(可选)系统消息,用于设定大模型的角色、语气、任务目标或约束条件等。一般放在messages数组的第一位。
contentstring(必选)系统指令,用于明确模型的角色、行为规范、回答风格和任务约束等。rolestring(必选)系统消息的角色,固定为system
User Messageobject(必选)用户消息,用于向模型传递问题、指令或上下文等。
contentstring 或 array(必选)消息内容。若输入只有文本,则为 string 类型;若输入包含图像数据,则为 array 类型。
textstring(必选)输入的文本。imagestring(可选)传入的图片文件。可以为图片的URL或本地路径。传入本地文件请参见传入本地文件示例值:{"image":"https://xxxx.jpeg","max-pixels":12802828}min_pixelsinteger(可选)用于设定输入图像的最小像素阈值,单位为像素。当输入图像像素小于min_pixels时,会将图像进行放大,直到总像素高于min_pixels默认值和最小值均为 3136 。与 image 参数一起使用,示例:{"image":"https://xxxx.jpeg","min_pixels":3136}max_pixelsinteger(可选)用于设定输入图像的最大像素阈值,单位为像素。当输入图像像素在[min_pixels, max_pixels]区间内时,模型会按原图进行识别。当输入图像像素大于max_pixels时,会将图像进行缩小,直到总像素低于max_pixels默认值和最大值和vl_high_resolution_images的取值有关:与 image 参数一起使用,示例:{"image":"https://xxxx.jpeg","max_pixels":1003520 }
Assistant Message object(可选)模型的回复。通常用于在多轮对话中作为上下文回传给模型。
contentstring(必选)模型回复的文本内容。rolestring(必选)助手消息的角色,固定为assistant
vl_high_resolution_imagesboolean(可选)默认值为false是否将输入图像的像素上限提升至 16384 Token 对应的像素值。
  • vl_high_resolution_images为true,使用固定分辨率策略,像素上限固定为12845056,忽略 max_pixels 设置,超过此分辨率时会将图像总像素缩小至此上限内。
  • vl_high_resolution_imagesfalse,像素上限由max_pixels决定,输入图像的像素超过max_pixels会将图像缩小至max_pixels内。模型的默认像素上限即max_pixels的默认值。
enable_thinking boolean (可选)使用混合思考模型时,是否开启思考模式。在界面交互系列模型中,仅gui-plus-2026-02-26为混合思考模型。相关文档:视觉推理可选值:
  • true:开启
    开启后,思考内容将通过reasoning_content字段返回。
  • false:不开启
不同模型的默认值:支持的模型
Java SDK 为enableThinking;通过HTTP调用时,请将 enable_thinking 放入 parameters 对象中。
max_tokensinteger(可选)用于限制模型输出的最大 Token 数。若生成内容超过此值,响应将被截断。默认值与最大值均为模型的最大输出长度,请参见模型选型
Java SDK中为maxTokens*。*通过HTTP调用时,请将 max_tokens放入 parameters 对象中。
seedinteger(可选)随机数种子。用于确保在相同输入和参数下生成结果可复现。若调用时传入相同的 seed 且其他参数不变,模型将尽可能返回相同结果。取值范围:[0,2 31 −1]
通过HTTP调用时,请将 seed放入 parameters 对象中。
temperaturefloat(可选)默认值为0.01采样温度,控制模型生成文本的多样性。temperature越高,生成的文本更多样,反之,生成的文本更确定。取值范围: [0, 2)temperature与top_p均可以控制生成文本的多样性,建议只设置其中一个值。
通过HTTP调用时,请将 temperature放入 parameters 对象中。
top_pfloat(可选)默认值为0.01核采样的概率阈值,控制模型生成文本的多样性。top_p越高,生成的文本更多样。反之,生成的文本更确定。取值范围:(0,1.0]temperature与top_p均可以控制生成文本的多样性,建议只设置其中一个值。
Java SDK中为topP*。*通过HTTP调用时,请将 top_p放入 parameters 对象中。
repetition_penaltyfloat(可选)默认值为1.0模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度,1.0表示不做惩罚。该参数对模型效果影响较大,建议保持默认值。
Java SDK中为repetitionPenalty*。*通过HTTP调用时,请将 repetition_penalty放入 parameters 对象中。
presence_penalty float(可选)控制模型生成文本时的内容重复度。默认值为1.5取值范围:[-2.0, 2.0]。正值降低重复度,负值增加重复度。在创意写作或头脑风暴等需要多样性、趣味性或创造力的场景中,建议调高该值;在技术文档或正式文本等强调一致性与术语准确性的场景中,建议调低该值。
如果参数值是正数,模型将对目前文本中已存在的Token施加一个惩罚值(惩罚值与文本出现的次数无关),减少这些Token重复出现的几率,从而减少内容重复度,增加用词多样性。
提示词:把这句话翻译成中文“This movie is good. The plot is good, the acting is good, the music is good, and overall, the whole movie is just good. It is really good, in fact. The plot is so good, and the acting is so good, and the music is so good.”参数值为2.0:这部电影很好。剧情很棒,演技棒,音乐也非常好听,总的来说,整部电影都好得不得了。实际上它真的很优秀。剧情非常精彩,演技出色,音乐也是那么的动听。参数值为0.0:这部电影很好。剧情好,演技好,音乐也好,总的来说,整部电影都很好。事实上,它真的很棒。剧情非常好,演技也非常出色,音乐也同样优秀。参数值为-2.0:这部电影很好。情节很好,演技很好,音乐也很好,总的来说,整部电影都很好。实际上,它真的很棒。情节非常好,演技也非常好,音乐也非常好。
top_kinteger(可选)默认值为1生成过程中采样候选集的大小。例如,取值为50时,仅将单次生成中得分最高的50个Token组成随机采样的候选集。取值越大,生成的随机性越高;取值越小,生成的确定性越高。取值为None或当top_k大于100时,表示不启用top_k策略,此时仅有top_p策略生效。取值需要大于或等于0。该参数非OpenAI标准参数。通过 Python SDK调用时,请放入 extra_body 对象中,配置方式为:extra_body={"top_k": xxx};通过 Node.js SDK 或 HTTP 方式调用时,请作为顶层参数传递。
Java SDK中为topK*。*通过HTTP调用时,请将 top_k放入 parameters 对象中。
repetition_penaltyfloat(可选)默认值为1.0模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度,1.0表示不做惩罚。该参数对模型效果影响较大,建议保持默认值。streamboolean(可选)是否以流式方式输出回复。可选值:
  • false:等待模型生成完整回复后一次性返回。
  • true:模型边生成边返回数据块。客户端需逐块读取,以还原完整回复。
该参数仅支持Python SDK。通过Java SDK实现流式输出请通过streamCall接口调用;通过HTTP实现流式输出请在Header中指定X-DashScope-SSEenable
incremental_outputboolean(可选)默认为false在流式输出模式下是否开启增量输出。推荐您优先设置为true参数值:
  • false:每次输出为当前已经生成的整个序列,最后一次输出为生成的完整结果。
I
I like
I like apple
I like apple.
  • true(推荐):增量输出,即后续输出内容不包含已输出的内容。您需要实时地逐个读取这些片段以获得完整的结果。
I
like
apple
.
Java SDK中为incrementalOutput*。*通过HTTP调用时,请将 incremental_output放入 parameters 对象中。
stopstring 或 array(可选)用于指定停止词。当模型生成的文本中出现stop 指定的字符串或token_id时,生成将立即终止。可传入敏感词以控制模型的输出。
stop为数组时,不可将token_id和字符串同时作为元素输入,比如不可以指定为["你好",104307]
  • 非流式输出
  • 流式输出
Python
import os
import dashscope
# 以下为华北2(北京)地域的配置,调用时请将WorkspaceId替换为真实的业务空间ID,各地域的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

system_prompt = """# Tools

You may call one or more functions to assist with the user query.

You are provided with function signatures within <tools></tools> XML tags:
<tools>
{"type": "function", "function": {"name": "computer_use", "description": "Use a mouse and keyboard to interact with a computer, and take screenshots.\\n* This is an interface to a desktop GUI. You do not have access to a terminal or applications menu. You must click on desktop icons to start applications.\\n* Some applications may take time to start or process actions, so you may need to wait and take successive screenshots to see the results of your actions. E.g. if you click on Firefox and a window doesn't open, try wait and taking another screenshot.\\n* The screen's resolution is 1000x1000.\\n* Make sure to click any buttons, links, icons, etc with the cursor tip in the center of the element. Don't click boxes on their edges unless asked.", "parameters": {"properties": {"action": {"description": "The action to perform. The available actions are:\\n* `key`: Performs key down presses on the arguments passed in order, then performs key releases in reverse order.\\n* `type`: Type a string of text on the keyboard.\\n* `mouse_move`: Move the cursor to a specified (x, y) pixel coordinate on the screen.\\n* `left_click`: Click the left mouse button at a specified (x, y) pixel coordinate on the screen.\\n* `left_click_drag`: Click and drag the cursor to a specified (x, y) pixel coordinate on the screen.\\n* `right_click`: Click the right mouse button at a specified (x, y) pixel coordinate on the screen.\\n* `middle_click`: Click the middle mouse button at a specified (x, y) pixel coordinate on the screen.\\n* `double_click`: Double-click the left mouse button at a specified (x, y) pixel coordinate on the screen.\\n* `triple_click`: Triple-click the left mouse button at a specified (x, y) pixel coordinate on the screen (simulated as double-click since it's the closest action).\\n* `scroll`: Performs a scroll of the mouse scroll wheel.\\n* `hscroll`: Performs a horizontal scroll (mapped to regular scroll).\\n* `wait`: Wait specified seconds for the change to happen.\\n* `terminate`: Terminate the current task and report its completion status.\\n* `answer`: Answer a question.\\n* `interact`: Resolve the blocking window by interacting with the user.", "enum": ["key", "type", "mouse_move", "left_click", "left_click_drag", "right_click", "middle_click", "double_click", "triple_click", "scroll", "hscroll", "wait", "terminate", "answer", "interact"], "type": "string"}, "keys": {"description": "Required only by `action=key`.", "type": "array"}, "text": {"description": "Required only by `action=type`, `action=answer` and `action=interact`.", "type": "string"}, "coordinate": {"description": "(x, y): The x (pixels from the left edge) and y (pixels from the top edge) coordinates to move the mouse to. Required only by `action=mouse_move` and `action=left_click_drag`.", "type": "array"}, "pixels": {"description": "The amount of scrolling to perform. Positive values scroll up, negative values scroll down. Required only by `action=scroll` and `action=hscroll`.", "type": "number"}, "time": {"description": "The seconds to wait. Required only by `action=wait`.", "type": "number"}, "status": {"description": "The status of the task. Required only by `action=terminate`.", "type": "string", "enum": ["success", "failure"]}}, "required": ["action"], "type": "object"}}}
</tools>

For each function call, return a json object with function name and arguments within <tool_call></tool_call> XML tags:
<tool_call>
{"name": <function-name>, "arguments": <args-json-object>}
</tool_call>

# Response format

Response format for every step:
1) Action: a short imperative describing what to do in the UI.
2) A single <tool_call>...</tool_call> block containing only the JSON: {"name": <function-name>, "arguments": <args-json-object>}.

Rules:
- Output exactly in the order: Action, <tool_call>.
- Be brief: one for Action.
- Do not output anything else outside those two parts.
- If finishing, use action=terminate in the tool call."""

messages = [
    {
        "role": "system",
        "content": system_prompt
    },
    {
        "role": "user",
        "content": [
            {"image": "https://img.alicdn.com/imgextra/i2/O1CN016iJ8ob1C3xP1s2M6z_!!6000000000026-2-tps-3008-1758.png"},
            {"text": "帮我打开浏览器。"}]
    }]

response = dashscope.MultiModalConversation.call(
    # 若没有配置环境变量, 请用百炼API Key将下行替换为: api_key = "sk-xxx"
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model='gui-plus-2026-02-26',
    messages=messages,
    vl_high_resolution_images=True
)

print(response.output.choices[0].message.content[0]["text"])

chat响应对象(流式与非流式输出格式一致)

status_codestring本次请求的状态码。200 表示请求成功,否则表示请求失败。
Java SDK不会返回该参数。调用失败会抛出异常,异常信息为status_codemessage的内容。
request_idstring本次调用的唯一标识符。
Java SDK返回参数为requestId。
codestring错误码,调用成功时为空值。
只有Python SDK返回该参数。
outputobject调用结果信息。

属性

textstring该参数当前固定为nullfinish_reasonstring模型结束生成的原因。有以下情况:
  • 正在生成时为null
  • 模型输出自然结束为stop
  • 因生成长度过长而结束为length
choicesarray模型的输出信息。
finish_reasonstring有以下情况:
  • 正在生成时为null
  • 因模型输出自然结束为stop
  • 因生成长度过长而结束为length
messageobject模型输出的消息对象。
rolestring输出消息的角色,固定为assistantcontentstring模型输出结果
audiostring该参数当前固定为null
usageobject本次请求使用的Token信息。

属性

input_tokens integer输入 Token 数。output_tokens integer输出 Token 数。image_tokens integer输入内容包含image时返回该字段。为用户输入图片内容转换成Token后的长度。characters integer该参数当前固定为nullinput_tokens_detailsobject输入 Token 的细粒度分类。
image_tokens integer模型输入的图像对应的 Token数。text_tokens integer模型输入的文本对应的Token 数。
output_tokens_detailsobject输出 Token 的细粒度分类。
text_tokens integer模型输入的文本对应的Token 数。
total_tokens integer消耗的总 Token 数,为input_tokensoutput_tokens的总和。
{
  "status_code": 200,
  "request_id": "b74b3a25-3968-4059-8c44-63d793c07f02",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "text": "```json\n{\"thought\": \"用户想要打开浏览器,我观察到屏幕截图中有一个Google Chrome的图标,其位置在右上角一排的最后一个。因此,下一步操作应该是点击这个Chrome浏览器图标来启动它。\", \"action\": \"CLICK\", \"parameters\": {\"x\": 1086, \"y\": 127}}\n```"
            }
          ]
        }
      }
    ],
    "audio": null
  },
  "usage": {
    "input_tokens": 2021,
    "output_tokens": 78,
    "characters": 0,
    "image_tokens": 1244,
    "input_tokens_details": {
      "image_tokens": 1244,
      "text_tokens": 777
    },
    "output_tokens_details": {
      "text_tokens": 78
    },
    "total_tokens": 2099
  }
}

错误码

如果模型调用失败并返回报错信息,请参见错误码进行解决。
GUI-Plus API参考 - 阿里云百炼