Skip to main content
More Models

GUI-Plus API reference

This topic describes the input and output parameters for calling the GUI-Plus model through the OpenAI-compatible interface or the DashScope API.

References: GUI-Plus: A dedicated model for interface interaction
The base_url and API key are region-specific. See Regions and endpoint URLs for endpoint URLs and obtain an API key to get your key.

OpenAI compatibility

For SDK calls, set the base_url to: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 For HTTP calls, set the endpoint to: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions
Before you begin, obtain an API key and configure the API key as an environment variable (This step is being deprecated and will be merged into configuring the API key). If you call the model using the OpenAI SDK, you must install the SDK.

Request body

modelstring(Required)The model name. Supported model: gui-plus.messagesarray(Required)The context to pass to the Large Language Model (LLM), arranged in conversational order.
System Messageobject(Optional)A system message that sets the role, tone, task objectives, or constraints for the LLM. It is usually placed first in the messages array.
contentstring(Required)System instructions that define the model's role, behavior, response style, and task constraints.rolestring(Required)The role of the system message. The value is fixed to system.
User Messageobject(Required)A user message.
contentarray(Required)The message content.
typestring(Required)Valid values:
  • text Set to text for text input.
  • image_url Set to image_url for image input.
textstring(Optional)The input text. This parameter is required when type is set to text.image_urlobjectThe input image information. This parameter is required when type is set to image_url.
url string(Required)The URL or Base64 Data URL of the image. To pass a local file, see Pass a local file.
min_pixelsinteger(Optional)Sets the minimum pixel threshold for the input image. The unit is pixels.If the input image has fewer pixels than min_pixels, the image is enlarged until its total pixel count exceeds min_pixels.The default and minimum value is 3136.max_pixelsinteger(Optional)Sets the maximum pixel threshold for the input image. The unit is pixels.If the pixel count of the input image is within the [min_pixels, max_pixels] range, the model processes the original image. If the pixel count exceeds max_pixels, the image is downscaled until its total pixel count is below max_pixels.The default and maximum values depend on the value of vl_high_resolution_images:
rolestring(Required)The role of the user message. The value is fixed to user.
Assistant Message object(Optional)The model's response. This is typically passed back to the model as context in a multi-turn conversation.
contentstring(Required)The text content of the model's response.rolestring(Required)The role of the assistant message. The value is fixed to assistant.
streamboolean(Optional) Default: falseSpecifies whether to return the response in a streaming manner.Valid values:
  • false: Waits for the model to generate the complete response and returns it at once.
  • true: The model generates and returns data blocks as they are created. The client must read the blocks sequentially to reconstruct the full response.
stream_optionsobject(Optional)Configuration items for streaming output. This parameter takes effect only when stream is set to true.

Properties

include_usageboolean(Optional) Default: falseSpecifies whether to include token usage information in the last data block.Valid values:
  • true: Include.
  • false: Do not include.
max_tokensinteger(Optional)Limits the maximum number of tokens in the model's output. If the generated content exceeds this value, the response is truncated.The default and maximum values are the model's maximum output length. For more information, see Scope of application.vl_high_resolution_imagesboolean(Optional) Default: falseSpecifies whether to increase the maximum pixel count of the input image to the value corresponding to 16384 tokens.
  • If vl_high_resolution_images is true, a fixed resolution policy is applied. The maximum pixel count is fixed at 12845056, and the max_pixels setting is ignored. If the image resolution exceeds this limit, the image's total pixel count is downscaled to fit within this limit.
  • If vl_high_resolution_images is false, the maximum pixel count is determined by max_pixels. If the pixel count of the input image exceeds max_pixels, the image is downscaled to fit within the max_pixels limit. The model's default maximum pixel count is the default value of max_pixels.
enable_thinking boolean (Optional)When using a hybrid thinking model (which can think before replying), specifies whether to enable the thinking mode. Among the interface interaction series models, only gui-plus-2026-02-26 is a hybrid thinking model. For more information, see Visual reasoning.Valid values:
  • true: Enable.
    If enabled, the thinking process content is returned in the reasoning_content field.
  • false: Disable.
This is not a standard OpenAI parameter. When calling with the Python SDK, place it in the extra_body object. The configuration is: extra_body={"enable_thinking": xxx}.
seedinteger(Optional)A random number seed. This ensures that results are reproducible with the same input and parameters. If you make a call with the same seed and other parameters unchanged, the model returns the same result as much as possible.Value range: [0,2<sup>31</sup>−1].temperaturefloat(Optional)Default: 0.01The sampling temperature, which controls the diversity of the text generated by the model.A higher temperature results in more diverse text. A lower temperature results in more deterministic text.Value range: [0, 2)Both temperature and top_p control the diversity of the generated text. We recommend setting only one of them.top_pfloat(Optional) Default: 0.01The probability threshold for nucleus sampling, which controls the diversity of the text generated by the model.A higher top_p results in more diverse text. A lower top_p results in more deterministic text.Value range: (0,1.0]Both temperature and top_p control the diversity of the generated text. We recommend setting only one of them.top_kinteger(Optional) Default: 1The size of the candidate set for sampling during generation. For example, a value of 50 means that only the 50 tokens with the highest scores in a single generation are used to form the random sampling candidate set. A larger value increases randomness. A smaller value increases determinism. A value of None or a value greater than 100 indicates that the top_k policy is not enabled, and only the top_p policy takes effect.The value must be greater than or equal to 0.This is not a standard OpenAI parameter. When calling with the Python SDK, place it in the extra_body object. The configuration is: extra_body={"top_k": xxx}. When calling with the Node.js SDK or by HTTP, pass it as a top-level parameter.repetition_penaltyfloat(Optional) Default: 1.0The degree of repetition in consecutive sequences during model generation. Increasing repetition_penalty reduces repetition. A value of 1.0 means no penalty. This parameter has a significant impact on the model's performance. We recommend keeping the default value.presence_penalty float(Optional)Controls content repetition when the model generates text. The default value is 1.5.Value range: [-2.0, 2.0]. Positive values reduce repetition. Negative values increase repetition.In scenarios that require diversity, interest, or creativity, such as creative writing or brainstorming, increase this value. In scenarios that emphasize consistency and terminological accuracy, such as technical documents or formal texts, decrease this value.
If the parameter value is positive, the model applies a penalty to tokens that already exist in the current text (the penalty is independent of the number of occurrences). This reduces the chance of these tokens reappearing, thereby reducing content repetition and increasing word diversity.
Prompt: Translate this sentence into Chinese: “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.”Parameter value is 2.0: This movie is great. The plot is fantastic, the acting is superb, and the music is beautiful. Overall, the entire film is simply outstanding. It is truly excellent, in fact. The story is very compelling, the performances are brilliant, and the score is so moving.Parameter value is 0.0: This movie is good. The plot is good, the acting is good, and the music is good. Overall, the whole movie is good. In fact, it is really great. The plot is very good, the acting is very good, and the music is also excellent.Parameter value is -2.0: This movie is good. The plot is good, the acting is good, and the music is good. Overall, the whole movie is good. In fact, it is really good. The plot is very good, the acting is very good, and the music is very good.
stopstring or array(Optional)Specifies stop words. When a string or token_id specified in stop appears in the generated text, generation stops immediately.You can pass sensitive words to control the model's output.
When stop is an array, you cannot mix token_ids and strings as elements. For example, ["Hello",104307] is not a valid specification.
  • Non-streaming output
  • Streaming output
  • 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": "Help me open the browser"}
        ]
    }
]

client = OpenAI(
    # If you have not configured the environment variable, replace the following line with your Model Studio 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 response object (non-streaming output)

idstringThe unique ID of this request.choicesarrayAn array of content generated by the model.

Properties

finish_reasonstringThe reason the model stopped generating.There are two cases:
  • stop if the output stopped naturally.
  • length if the generation ended because it was too long.
indexintegerThe index of the current object in the choices array.messageobjectThe message output by the model.

Properties

content stringThe result of the GUI task.refusal stringThis parameter is currently fixed to null.role stringThe role of the message. The value is fixed to assistant.audio objectThis parameter is currently fixed to null.function_call objectThis parameter is currently fixed to null.tool_calls arrayThis parameter is currently fixed to null.
createdintegerThe UNIX timestamp when this request was created.modelstringThe model used for this request.object stringAlways chat.completion.service_tier stringThis parameter is currently fixed to null.system_fingerprintstringThis parameter is currently fixed to null.usage objectToken usage information for this request.
completion_tokens integerThe number of tokens in the model's output.prompt_tokens integerThe number of tokens in the input.total_tokens integerThe total number of tokens used, which is the sum of prompt_tokens and completion_tokens.completion_tokens_details objectA fine-grained categorization of the model's output tokens.
accepted_prediction_tokensintegerThis parameter is currently fixed to null.audio_tokens integerThis parameter is currently fixed to null.reasoning_tokens integerThis parameter is currently fixed to null.text_tokens integerThe number of tokens corresponding to the model's output text.rejected_prediction_tokensintegerThis parameter is currently fixed to null.
prompt_tokens_details objectA fine-grained categorization of the input tokens.
audio_tokens integerThis parameter is currently fixed to null.cached_tokens integerThis parameter is currently fixed to null.text_tokens integerThe number of tokens corresponding to the model's input text.image_tokens integerThe number of tokens corresponding to the model's input image.
{
  "id": "chatcmpl-ef17511a-aceb-4c47-8757-13a87af2152d",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "```json\n{\"thought\": \"The user wants to open the browser. I see a Google Chrome icon in the screenshot. It is the last one in the top-right row. The next step should be to click this Chrome browser icon to launch it.\", \"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 response chunk object (streaming output)

idstringThe unique ID of this call. Each chunk object has the same ID.choicesarrayAn array of content generated by the model. If the include_usage parameter is set to true, this is empty in the last chunk.

Properties

delta objectThe output content returned in the stream.

Properties

content stringqwen-mt-flash provides incremental updates for translation results, while qwen-mt-plus provides non-incremental updates.function_call objectThis parameter is currently fixed to null.refusal objectThis parameter is currently fixed to null.role stringThe role of the message object. This has a value only in the first chunk.
finish_reason stringThe reason the model stopped generating. There are three cases:
  • stop if the output stopped naturally.
  • null if generation is not finished.
  • length if the generation ended because it was too long.
index integerThe index of the current response in the choices array.
createdintegerThe UNIX timestamp when this request was created. Each chunk has the same timestamp.modelstringThe model used for this request.object stringAlways chat.completion.chunk.service_tier stringThis parameter is currently fixed to null.system_fingerprintstringThis parameter is currently fixed to null.usage objectThe tokens used by this request. This is returned only in the last chunk when include_usage is true.
completion_tokens integerThe number of tokens in the model's output.prompt_tokens integerThe number of tokens in the input.total_tokens integerThe total number of tokens used, which is the sum of prompt_tokens and completion_tokens.completion_tokens_details objectA fine-grained categorization of the model's output tokens.
accepted_prediction_tokensintegerThis parameter is currently fixed to null.audio_tokens integerThis parameter is currently fixed to null.reasoning_tokens integerThis parameter is currently fixed to null.text_tokens integerThe number of tokens corresponding to the model's output text.rejected_prediction_tokensintegerThis parameter is currently fixed to null.
prompt_tokens_details objectA fine-grained categorization of the input tokens.
audio_tokens integerThis parameter is currently fixed to null.cached_tokens integerThis parameter is currently fixed to null.text_tokens integerThe number of tokens corresponding to the model's input text.image_tokens integerThe number of tokens corresponding to the model's input image.
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 request address: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
  • SDK call: Set base_url to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1.
Before you begin, obtain an API key and configure the API key as an environment variable (This step is being deprecated and will be merged into configuring the API key). If you call the model using the DashScope SDK, you must install the DashScope SDK.

Request body

modelstring(Required)The model name. Supported model: gui-plus.messagesarray(Required)The context to pass to the LLM, arranged in conversational order.
When making an HTTP call, place messages in the input object.
System Messageobject(Optional)A system message that sets the role, tone, task objectives, or constraints for the LLM. It is usually placed first in the messages array.
contentstring(Required)System instructions that define the model's role, behavior, response style, and task constraints.rolestring(Required)The role of the system message. The value is fixed to system.
User Messageobject(Required)A user message used to pass questions, instructions, or context to the model.
contentstring or array(Required)The message content. This is a string if the input is text-only. It is an array if the input includes image data.
textstring(Required)The input text.imagestring(Optional)The image file to pass. This can be the URL of the image or a local path. To pass a local file, see Pass a local file.Example: {"image":"https://xxxx.jpeg","max-pixels":12802828}min_pixelsinteger(Optional)Sets the minimum pixel threshold for the input image. The unit is pixels.If the input image has fewer pixels than min_pixels, the image is enlarged until its total pixel count exceeds min_pixels.The default and minimum value is 3136.Use with the image parameter. Example: {"image":"https://xxxx.jpeg","min_pixels":3136}max_pixelsinteger(Optional)Sets the maximum pixel threshold for the input image. The unit is pixels.If the pixel count of the input image is within the [min_pixels, max_pixels] range, the model processes the original image. If the pixel count exceeds max_pixels, the image is downscaled until its total pixel count is below max_pixels.The default and maximum values depend on the value of vl_high_resolution_images:Use with the image parameter. Example: {"image":"https://xxxx.jpeg","max_pixels":1003520 }
Assistant Message object(Optional)The model's response. This is typically passed back to the model as context in a multi-turn conversation.
contentstring(Required)The text content of the model's response.rolestring(Required)The role of the assistant message. The value is fixed to assistant.
vl_high_resolution_imagesboolean(Optional) Default: falseSpecifies whether to increase the maximum pixel count of the input image to the value corresponding to 16384 tokens.
  • If vl_high_resolution_images is true, a fixed resolution policy is applied. The maximum pixel count is fixed at 12845056, and the max_pixels setting is ignored. If the image resolution exceeds this limit, the image's total pixel count is downscaled to fit within this limit.
  • If vl_high_resolution_images is false, the maximum pixel count is determined by max_pixels. If the pixel count of the input image exceeds max_pixels, the image is downscaled to fit within the max_pixels limit. The model's default maximum pixel count is the default value of max_pixels.
enable_thinking boolean (Optional)When using a hybrid thinking model, specifies whether to enable the thinking mode. Among the interface interaction series models, only gui-plus-2026-02-26 is a hybrid thinking model. For more information, see Visual reasoning.Valid values:
  • true: Enable.
    If enabled, the thinking process content is returned in the reasoning_content field.
  • false: Disable.
Default values for different models: Supported models
The Java SDK uses enableThinking. When making an HTTP call, place enable_thinking in the parameters object.
max_tokensinteger(Optional)Maximum number of tokens to generate. If the output exceeds this value, the response is truncated.The default and maximum values are the maximum output length of the model. For more information, see Model selection.
In the Java SDK, the parameter is maxTokens. When you call via HTTP, place max_tokens in the parameters object.
seedinteger(Optional)Random number seed for reproducible results. Using the same seed and parameters produces consistent output.Value range: [0, 2 31 -1].
When making an HTTP call, place seed in the parameters object.
temperaturefloat(Optional)Default: 0.01The sampling temperature, which controls the diversity of the text generated by the model.A higher temperature results in more diverse text. A lower temperature results in more deterministic text.Value range: [0, 2)Both temperature and top_p control the diversity of the generated text. We recommend setting only one of them.
When making an HTTP call, place temperature in the parameters object.
top_pfloat(Optional) Default: 0.01The probability threshold for nucleus sampling, which controls the diversity of the text generated by the model.A higher top_p results in more diverse text. A lower top_p results in more deterministic text.Value range: (0,1.0]Both temperature and top_p control the diversity of the generated text. We recommend setting only one of them.
In the Java SDK, the parameter is named topP. When you make HTTP calls, include top_p in the parameters object.
repetition_penaltyfloat(Optional) Default: 1.0The degree of repetition in consecutive sequences during model generation. Increasing repetition_penalty reduces repetition. A value of 1.0 means no penalty. This parameter has a significant impact on the model's performance. We recommend keeping the default value.
In the Java SDK, this parameter is named repetitionPenalty. When you make an HTTP call, place repetition_penalty in the parameters object.
presence_penalty float(Optional)Controls content repetition when the model generates text. The default value is 1.5.Value range: [-2.0, 2.0]. Positive values reduce repetition. Negative values increase repetition.In scenarios that require diversity, interest, or creativity, such as creative writing or brainstorming, increase this value. In scenarios that emphasize consistency and terminological accuracy, such as technical documents or formal texts, decrease this value.
If the parameter value is positive, the model applies a penalty to tokens that already exist in the current text (the penalty is independent of the number of occurrences). This reduces the chance of these tokens reappearing, thereby reducing content repetition and increasing word diversity.
Prompt: Translate this sentence into Chinese: “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.”Parameter value is 2.0: This movie is great. The plot is fantastic, the acting is superb, and the music is beautiful. Overall, the entire film is simply outstanding. It is truly excellent, in fact. The story is very compelling, the performances are brilliant, and the score is so moving.Parameter value is 0.0: This movie is good. The plot is good, the acting is good, and the music is good. Overall, the whole movie is good. In fact, it is really great. The plot is very good, the acting is very good, and the music is also excellent.Parameter value is -2.0: This movie is good. The plot is good, the acting is good, and the music is good. Overall, the whole movie is good. In fact, it is really good. The plot is very good, the acting is very good, and the music is very good.
top_kinteger(Optional) Default: 1The size of the candidate set for sampling during generation. For example, a value of 50 means that only the 50 tokens with the highest scores in a single generation are used to form the random sampling candidate set. A larger value increases randomness. A smaller value increases determinism. A value of None or a value greater than 100 indicates that the top_k policy is not enabled, and only the top_p policy takes effect.The value must be greater than or equal to 0.This is not a standard OpenAI parameter. When calling with the Python SDK, place it in the extra_body object. The configuration is: extra_body={"top_k": xxx}. When calling with the Node.js SDK or by HTTP, pass it as a top-level parameter.
The Java SDK uses topKtop_k in the parameters object.
repetition_penaltyfloat(Optional) Default: 1.0The degree of repetition in consecutive sequences during model generation. Increasing repetition_penalty reduces repetition. A value of 1.0 means no penalty. This parameter has a significant impact on the model's performance. We recommend keeping the default value.streamboolean(Optional)Specifies whether to return the response in a streaming manner.Valid values:
  • false: Waits for the model to generate the complete response and returns it at once.
  • true: The model generates and returns data blocks as they are created. The client must read the blocks sequentially to reconstruct the full response.
This parameter is supported only by the Python SDK. To implement streaming output with the Java SDK, use the streamCall interface. To implement streaming output by HTTP, specify X-DashScope-SSE as enable in the header.
incremental_outputboolean(Optional) Default: falseSpecifies whether to enable incremental output in streaming mode. We recommend that you set this to true.Parameter values:
  • false: Each output is the entire sequence generated so far. The final output is the complete result.
I
I like
I like apple
I like apple.
  • true (Recommended): Incremental output. Subsequent outputs do not include previously sent content. You must read these fragments in real time to get the complete result.
I
like
apple
.
In the Java SDK, this parameter is called incrementalOutput. When making HTTP calls, include incremental_output in the parameters object.
stopstring or array(Optional)Specifies stop words. When a string or token_id specified in stop appears in the generated text, generation stops immediately.You can pass sensitive words to control the model's output.
When stop is an array, you cannot mix token_ids and strings as elements. For example, ["Hello",104307] is not a valid specification.
  • Non-streaming output
  • Streaming output
Python
import os
import dashscope

# China (Beijing) region. Replace {WorkspaceId} with your Workspace ID. URLs vary by region.
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": "Help me open the browser."}]
    }]

response = dashscope.MultiModalConversation.call(
    # If you have not configured the environment variable, replace the following line with your Model Studio 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 response object (same format for streaming and non-streaming output)

status_codestringThe status code of this request. A value of 200 indicates that the request was successful. Otherwise, the request failed.
The Java SDK does not return this parameter. If the call fails, an exception is thrown. The exception message contains the content of status_code and message.
request_idstringThe unique ID of this call.
The Java SDK returns this parameter as requestId
codestringThe error code. This is empty if the call is successful.
Only the Python SDK returns this parameter.
outputobjectInformation about the call result.

Properties

textstringThis parameter is currently fixed to null.finish_reasonstringThe reason the model stopped generating. The possible cases are:
  • null if generation is in progress.
  • The model output ends naturally with stop.
  • length if the generation ended because it was too long.
choicesarrayThe model's output information.
finish_reasonstringThe possible cases are:
  • null if generation is in progress.
  • The model output naturally ends with stop.
  • length if the generation ended because it was too long.
messageobjectThe message object output by the model.
rolestringThe role of the output message. The value is fixed to assistant.contentstringThe model's output result
audiostringThis parameter is currently fixed to null.
usageobjectToken information used by this request.

Properties

input_tokens integerThe number of input tokens.output_tokens integerThe number of output tokens.image_tokens integerThis field is returned when the input content includes an image. It is the length of the user's input image content after being converted to tokens.characters integerThis parameter is currently fixed to null.input_tokens_detailsobjectA fine-grained categorization of the input tokens.
image_tokens integerThe number of tokens corresponding to the model's input image.text_tokens integerThe number of tokens corresponding to the model's input text.
output_tokens_detailsobjectA fine-grained categorization of the output tokens.
text_tokens integerThe number of tokens corresponding to the model's input text.
total_tokens integerThe total number of tokens used, which is the sum of input_tokens and output_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\": \"The user wants to open the browser. I see a Google Chrome icon in the screenshot. It is the last one in the top-right row. The next step should be to click this Chrome browser icon to launch it.\", \"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
  }
}

Error codes

If the model call fails and an error message is returned, see Error messages to resolve the issue.
API Usage
Text Generation
Image Generation
Video Generation
World models
3D Model Generation
Audio
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
Translation models
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More