DashScope API Reference

Request body

modelstring(Required)

The name of the model to use.

Supported models include Qwen large language models (commercial and open source editions), Qwen-VL, Qwen-Coder, Qwen-Audio, math models, DeepSeek (provided by Alibaba Cloud and SiliconFlow), Kimi (provided by Alibaba Cloud), GLM (provided by Alibaba Cloud), and MiniMax (provided by Alibaba Cloud and MiniMax).

For specific model names and billing details, seeSelect a model.

messagesarray(Required)

The context to pass to the large language model (LLM), arranged in conversational order.

When you call over HTTP, place messages in the input object.

temperaturefloat(Optional)

The sampling temperature, which controls the diversity of the text that is generated by the model.

A higher temperature results in more diverse text, and a lower temperature results in more deterministic text.

Value range: [0, 2)

When you call over HTTP, place temperature in the parameters object.

We do not recommend that you modify the default temperature value for QVQ models.

top_pfloat(Optional)

The probability threshold for nucleus sampling, which controls the diversity of the text that is generated by the model.

A higher top_p value results in more diverse text, and a lower top_p value results in more deterministic text.

Value range: (0, 1.0].

In the Java SDK, this parameter is topP. When you call over HTTP, place top_p in the parameters object.

We do not recommend that you modify the default top_p value for QVQ models.

top_kinteger(Optional)

The size of the candidate set for sampling during generation. For example, if you set this parameter to 50, only the 50 tokens with the highest scores in a single generation are used to form the candidate set for random sampling. A larger value increases randomness, and a smaller value increases determinism. A value of None or a value greater than 100 indicates that the top_k strategy is not enabled and only the top_p strategy takes effect.

The value must be greater than or equal to 0.

In the Java SDK, this parameter is topK. When you call over HTTP, place top_k in the parameters object.

We do not recommend that you modify the default top_k value for QVQ models.

enable_thinking boolean (Optional)

Specifies whether to enable thinking mode for a hybrid thinking model. This applies to Qwen3.7, Qwen3.6, Qwen3.5, Qwen3, and Qwen3-VL models, along with the DeepSeek-V4-Pro/V4-Flash series (provided by Alibaba Cloud), DeepSeek-V3.2/V3.2-exp/V3.1 series (provided by Alibaba Cloud and SiliconFlow), Kimi-K2.6/K2.5 series (provided by Alibaba Cloud), and GLM series. The DeepSeek-V4 series has thinking mode enabled by default. You can adjust the inference effort with the reasoning_effort parameter.

Valid values:

• true: The feature is enabled.

  If enabled, the thinking content is returned in the reasoning_content field.

• false: Disabled

For the default values for different models, see Supported models.

In the Java SDK, this parameter is enableThinking. When you call over HTTP, place enable_thinking in the parameters object.

preserve_thinking boolean (Optional) The default value is false. (Default value for qwen3.8-max/qwen3.8-flash:true)

Specifies whether to append the reasoning_content from assistant messages in the conversation history to the model input. This is suitable for scenarios where the model needs to refer to the historical thinking process.

Currently supported by qwen3.7-max, qwen3.7-max-2026-05-20 and subsequent snapshots, qwen3.6-max-preview, qwen3.7-plus, qwen3.7-plus-2026-05-26, qwen3.6-plus, qwen3.6-plus-2026-04-02, qwen3.7-flash, qwen3.7-flash-2026-07-15, qwen3.6-flash, qwen3.6-flash-2026-04-16, qwen3.8-max (enabled by default), qwen3.8-max-0902 (enabled by default), qwen3.8-flash (enabled by default), kimi-k2.6 (deployed on Alibaba Cloud Model Studio), kimi-k2.7-code (deployed on Alibaba Cloud Model Studio, enabled by default), kimi/kimi-k2.7-code-highspeed (supplied by Moonshot AI, enabled by default), and kimi/kimi-k2.7-code (supplied by Moonshot AI, enabled by default).

Important (qwen3.8-max/qwen3.8-flash): When using qwen3.8-max/qwen3.8-flash, preserve_thinking defaults to true. You must send back all historical reasoning_content in the reasoning_content field. Do NOT concatenate reasoning_content into the content field. Doing so may degrade model performance.

• If the historical messages do not contain reasoning_content, enabling this parameter does not cause an error.
• When enabled, the reasoning_content from the historical conversation is included in the input token count and is billed.

When you call over HTTP, place preserve_thinking in the parameters object. The Java SDK is not supported.

thinking_budget integer (Optional)

The maximum length of the thinking process. This applies to Qwen3.8, Qwen3.7, Qwen3.6, Qwen3.5, Qwen3-VL, Qwen3, GLM(supplied by Alibaba Cloud) and Kimi(supplied by Alibaba Cloud) models, except kimi-k3, which does not support this parameter. For more information, see Limit thinking length.

The default value is the maximum chain-of-thought length for the model. For more information, see Select a model.

In the Java SDK, this parameter is thinkingBudget. When you call over HTTP, place thinking_budget in the parameters object.

The default value is the maximum chain-of-thought length for the model.

reasoning_effort string (Optional)

Controls the inference intensity of models. The valid values and default values vary by model.

DeepSeek-V4 and GLM series (Default value: high)

Valid values: high (high-intensity inference) and max (maximum-intensity inference). low and medium are mapped to high, and xhigh is mapped to max.

This applies to glm-5.2, glm-5.1, glm-5, deepseek-v4-pro, and deepseek-v4-flash (provided by Alibaba Cloud).

Qwen3.8 series models: Default value:xhigh

Valid values:

• xhigh (default): Maximum-intensity inference
• medium: Standard inference
• low: Low-intensity inference

OpenAI standard value mapping: max is mapped to xhigh, high is mapped to xhigh, minimal is mapped to low, and none is mapped to enable_thinking=False.

Setting values other than the above valid values and mapped values will cause an error.

For the qwen3.8 series, reasoning_effort and thinking_budget cannot be set at the same time. Setting both will cause an error. However, they support mutual conversion:

• When thinking_budget is not set, the reasoning_effort levels are automatically mapped to thinking_budget: low corresponds to 4096, medium corresponds to 16384, and xhigh corresponds to 262144.
• When reasoning_effort is not set, thinking_budget is automatically mapped back to reasoning_effort: 0–4096 corresponds to low, 4097–16384 corresponds to medium, and 16385–262144 corresponds to xhigh.
• When neither is set, the default thinking_budget (131072) and default reasoning_effort (xhigh) are used.

When you call over HTTP, place reasoning_effort in the parameters object.

tool_stream boolean (Optional) The default value is false.

This parameter only affects the streaming output behavior of complex tool parameters and is effective only in streaming calls. Simple tool parameters, where all parameter types are strings, can be streamed as long as streaming calls are enabled. tool_stream has no effect on them. Complex tools are tools where some parameter types in the tool definition are arrays or objects. Currently, only the Qwen and GLM series support this.

• qwen-max series: Text modality of the qwen3.8-max and qwen3.7-max series
• qwen-plus series: Text modality of the qwen3.7-plus and qwen3.6-plus series, and all modalities of the qwen3.5-plus series
• qwen-flash series: All modalities of the qwen3.8-flash, qwen3.7-flash, qwen3.6-flash and qwen3.5-flash series

• tool_stream=false: Complex tool parameters are output all at once. This is the default behavior, and the complex format is more accurate.
• tool_stream=true: Complex tool parameters are streamed. This avoids the risk of timeout for complex formats.

Complex tools are tools where some parameter types in the tool definition are arrays or objects.

GLM series support list: glm-4.6, glm-4.7, glm-5, and glm-5.1 (provided by Alibaba Cloud).

• tool_stream=false: Tool parameters are output all at once. This is the default behavior, and the complex format is more accurate.
• tool_stream=true: Tool parameters are streamed. This avoids the risk of timeout for complex formats.

When you call over HTTP, place tool_stream in the parameters object.

enable_code_interpreter boolean (Optional) The default value is false.

Specifies whether to enable the code interpreter feature. For more information, see Code interpreter.

Valid values:

• true: Enables the feature.
• false: Disables the feature.

The Java SDK is not supported. When you call over HTTP, place enable_code_interpreter in the parameters object.

clear_thinkingboolean(Optional) The default value is false.

Controls whether to use the reasoning_content (thinking process) from previous turns as context input for the model in a multi-turn conversation. This is supported only by the GLM series models glm-5.2, glm-5.1, glm-5, and glm-4.7.

• true: Enables the feature. This ignores the reasoning_content from previous turns and uses only visible text, tool calls, and results as context input. This can reduce context length and cost.
• false (default): Disables the feature. This retains the reasoning_content from previous turns and provides it to the model along with the context. If you want to enable preserved thinking, you must pass the historical reasoning_content completely, unmodified, and in its original order in the messages. Missing, trimming, rewriting, or reordering degrades performance or prevents the feature from taking effect.

repetition_penaltyfloat(Optional)

The penalty for repeating consecutive sequences during model generation. A higher repetition_penalty value can reduce repetition in the model's output. A value of 1.0 indicates no penalty. The value must be greater than 0.

In the Java SDK, this parameter is repetitionPenalty. When you call over HTTP, place repetition_penalty in the parameters object.

When you use the qwen-vl-plus_2025-01-25 model for text extraction, we recommend that you set repetition_penalty to 1.0.

We do not recommend that you modify the default repetition_penalty value for QVQ models.

presence_penaltyfloat(Optional)

Controls the content repetition when the model generates text.

Value range: [-2.0, 2.0]. Positive values reduce repetition, while negative values increase it.

In scenarios that require diversity, fun, or creativity, such as creative writing or brainstorming, you can increase this value. In scenarios that emphasize consistency and term accuracy, such as technical documents or formal texts, you can decrease this value.

When you use the qwen-vl-plus model for text extraction, set presence_penalty to 1.5.

Do not modify the default presence_penalty value for QVQ models.

The Java SDK does not support setting this parameter*.* When you call over HTTP, place presence_penalty in the parameters object.

vl_high_resolution_imagesboolean(Optional) Default value: false

Specifies whether to increase the pixel limit for input images to the pixel count that corresponds to 16384 tokens. For more information, see Processing high-resolution images.

• vl_high_resolution_images: true uses a fixed resolution strategy and ignores the max_pixels setting. If the resolution is exceeded, the total pixel count of the image is scaled down to stay within this limit.

  Click to view the pixel limits for each model

  When vl_high_resolution_images is True, the pixel limits vary by model:

  • For the Qwen3.8 series, Qwen3.7 series, Qwen3.6 series, Qwen3.5 series, Qwen3-VL series, qwen-vl-max, qwen-vl-max-0813, qwen-vl-plus, qwen-vl-plus-0815, and qwen-vl-plus-0710 models, the value is 16777216. (Each Token corresponds to 32*32 pixels. The total value is calculated as 16384*32*32.)
  • QVQ series, other Qwen2.5-VL series models: 12845056 (1 token corresponds to 28*28 pixels, which is 16384*28*28)

• vl_high_resolution_images is false, the pixel limit is determined by max_pixels. If the input image's pixel count exceeds max_pixels, the image is scaled down to within the max_pixels limit. The default pixel limit for each model is the default value of max_pixels.

In the Java SDK, this parameter is vlHighResolutionImages (requires V2.20.8 or later). When you call over HTTP, place vl_high_resolution_images in the parameters object.

vl_enable_image_hw_outputboolean(Optional) The default value is false.

Specifies whether to return the dimensions of the scaled image. The model scales the input image. If you set this parameter to True, it returns the height and width of the scaled image. If streaming output is enabled, this information is returned in the last chunk. This is supported by Qwen-VL models.

In the Java SDK, this parameter is vlEnableImageHwOutput. The minimum required Java SDK version is 2.20.8*.* When you call over HTTP, place vl_enable_image_hw_output in the parameters object.

max_tokensinteger(Optional, to be deprecated)

This parameter will be deprecated. For new integrations, use max_completion_tokens.

The meaning of this parameter varies by model:

• deepseek-v4-pro, deepseek-v4-pro-0813, deepseek-v4-flash, deepseek-v4-flash-0731: The maximum number of tokens for the sum of the model's answer and chain-of-thought content. If the model's output exceeds this value, generation stops early, and the returned finish_reason is length.
• glm-5.2: When the thinking_budget parameter is not passed, max_tokens is the maximum number of tokens for the sum of the model's answer and chain-of-thought content, and if the model's output exceeds this value, generation stops early with the returned finish_reason being length. When the thinking_budget parameter is passed, max_tokens is the maximum number of tokens for the model's answer only, and the number of tokens for the chain-of-thought part is controlled separately by thinking_budget.
• Other models: The maximum number of tokens for the model's answer (excluding chain-of-thought). If the generated content exceeds this value, generation stops early, and the returned finish_reason is length.

The default and maximum values are both the model's maximum output length.

In the Java SDK, this parameter is maxTokens. For Qwen-VL/Audio models, it is maxLength in the Java SDK, but versions later than 2.18.4 also support setting it as maxTokens. When you call over HTTP, place max_tokens in the parameters object.

max_completion_tokensinteger(Optional)

The maximum length of the model's output, including the chain-of-thought and the model's answer. If the model's output exceeds this value, generation stops early, and the returned finish_reason is length.

The default and maximum values are both the model's maximum output length.

Difference from max_tokens: max_completion_tokens limits the complete model output (chain-of-thought + answer), while max_tokens only limits the answer part. For thinking models, we recommend that you use max_completion_tokens.

The following models are supported:

• Qwen Max: Qwen3.7-Max and later models
• Qwen Plus: Qwen3.5-Plus and later models
• Qwen Flash: Qwen3.5-Flash and later models
• Kimi: kimi-k2.5 and later models
• GLM: glm-5 and later models
• MiniMax: MiniMax-M2.5 and later models
• DeepSeek: deepseek-v3, deepseek-r1, deepseek-r1-0528, deepseek-v3.1, deepseek-v3.2, deepseek-v3.2-exp, deepseek-v4-pro, deepseek-v4-flash, and later models

The models listed above do not include models supplied directly by third parties.

There may be a difference of up to 10 tokens between the actual output token count and the specified max_completion_tokens value.

The Java SDK does not currently support this parameter. When you call over HTTP, place max_completion_tokens in the parameters object.

seedinteger(Optional)

A random number seed. This parameter is used to ensure reproducible results with the same input and parameters. If you pass the same seed value in a call and other parameters remain unchanged, the model returns the same result as much as possible.

Value range: [0,2<sup>31</sup>−1].

When you call over HTTP, place seed in the parameters object.

streamboolean(Optional)The default value is false.

Specifies whether to stream the reply. The valid values are:

• false: The model generates all content and then returns the result at once.
• true: The model generates and outputs content on the fly. This means that the model immediately outputs a chunk of content as soon as it is generated.

This parameter is supported only by the Python SDK. To implement streaming output with the Java SDK, call the streamCall interface. To implement streaming output over HTTP, specify X-DashScope-SSE as enable in the header.

Qwen3 commercial edition (thinking mode), Qwen3 open source edition, QwQ, and QVQ support only streaming output.

incremental_outputboolean(Optional) The default is false. For Qwen3-Max, Qwen3-VL, Qwen3 open source edition, QwQ, and QVQ models, the default is true.

Specifies whether to enable incremental output in streaming output mode. We recommend that you set this parameter to true.

Value:

• false: Each output contains the entire sequence that is generated so far. The last output is the complete generated result.

I
I like
I like apple
I like apple.

• true (recommended): The output is incremental. Subsequent output does not include previously output content. You must read these chunks one by one in real time to obtain the complete result.

I
like
apple
.

In the Java SDK, this parameter is incrementalOutput. When you call over HTTP, place incremental_output in the parameters object.

QwQ models and Qwen3 models in thinking mode support only setting this parameter to true. Because the default value for Qwen3 commercial edition models is false, you must manually set it to true in thinking mode.

Qwen3 open source edition models do not support setting this parameter to false.

response_formatobject (Optional) The default value is {"type": "text"}.

The format of the returned content. The valid values are:

• {"type": "text"}: Outputs a text reply.
• {"type": "json_object"}: Outputs a JSON string in a standard format.

For more information, see Structured output.

For a list of supported models, see Supported models.

If you specify {"type": "json_object"}, you must explicitly instruct the model to output JSON in the prompt, such as "Please output in JSON format". Otherwise, an error occurs.

In the Java SDK, this parameter is responseFormat. When you call over HTTP, place response_format in the parameters object.

result_formatstring(Optional)The default is text. For Qwen3-Max, Qwen3-VL, QwQ models, Qwen3 open source models (except qwen3-next-80b-a3b-instruct) and Qwen-Long models, the default is message.

The format of the returned data. We recommend that you set this parameter to message to facilitate multi-turn conversations.

The platform will later unify the default value to message.

In the Java SDK, this parameter is resultFormat. When you call over HTTP, place result_format in the parameters object.

If the model is Qwen-VL, QVQ, or Audio, setting the value to text has no effect.

Qwen3-Max, Qwen3-VL, and Qwen3 models in thinking mode can only be set to message. Because the default value for Qwen3 commercial edition models is text, you need to set it to message.

If you use the Java SDK to call a Qwen3 open source model and pass text, the response is still returned in message format.

logprobs boolean (Optional) The default value is false.

Specifies whether to return the log probabilities of the output tokens. The valid values are:

• true

  Back

• false

  You cannot return.

The following models are supported:

• Snapshot models of the qwen-plus series (excluding stable edition models)
• Snapshot models of the qwen-turbo series (excluding stable edition models)
• qwen3-vl-plus series (including stable edition models)
• qwen3-vl-flash series (including stable edition models)
• Qwen3 open source models

When you call over HTTP, place logprobs in the parameters object.

top_logprobs integer (Optional) The default value is 0.

Specifies the number of most likely candidate tokens to return at each generation step.

Value range: [0, 5]

This parameter takes effect only if logprobs is true.

In the Java SDK, this parameter is topLogprobs. When you call over HTTP, place top_logprobs in the parameters object.

ninteger(Optional) The default value is 1.

The number of responses to generate. The value range is 1-4. For scenarios that require multiple responses to be generated, such as creative writing or ad copy, you can set a larger n value.

Currently, only Qwen3 (non-thinking mode) and qwen-plus-character models are supported. The value is fixed at 1 if the tools parameter is passed.

Setting a larger n value does not increase input token consumption but does increase output token consumption.

When you call over HTTP, place n in the parameters object.

stopstring or array(Optional)

Used to specify 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 input both token_id and strings as elements. For example, you cannot specify ["Hello",104307].

When you call over HTTP, place stop in the parameters object.

toolsarray(Optional)

An array that contains one or more tool objects for the model to call during function calling. For more information, see Function calling.

When you use tools, you must set result_format to message.

When you initiate function calling or submit tool execution results, you must set the tools parameter.

When you call over HTTP, place tools in the parameters object. This is temporarily not supported for qwen-vl and qwen-audio series models.

tool_choicestring or object(Optional) The default value is auto.

The tool selection strategy. You can set this parameter to force a tool call method for a specific type of problem, such as always using a certain tool or disabling all tools.

• auto

  The LLM chooses the tool strategy autonomously.

• none

  If you want to temporarily disable tool calls in a specific request, you can set the tool_choice parameter to none.

• {"type": "function", "function": {"name": "the_function_to_call"}}

  If you want to force a call to a specific tool, you can set the tool_choice parameter to {"type": "function", "function": {"name": "the_function_to_call"}}, where the_function_to_call is the name of the specified tool function.

  Models in thinking mode do not support forcing a call to a specific tool.

In the Java SDK, this parameter is toolChoice. When you call over HTTP, place tool_choice in the parameters object.

parallel_tool_calls boolean (Optional) The default value is false.

Specifies whether to enable parallel tool calls.

Valid values:

• true: Enabled
• false: Disabled.

For more information about parallel tool calls, see Parallel tool calls.

In the Java SDK, this parameter is parallelToolCalls. When you call over HTTP, place parallel_tool_calls in the parameters object.

enable_searchboolean(Optional)The default value is false.

Specifies whether the model uses Internet search results as a reference when it generates text. The valid values are:

• true: Enables Internet search. The model uses search results as reference information during text generation, but the model decides whether to use the Internet search results based on its internal logic.

  If web search is not performed after enabling, you can optimize the prompt or set the forced_search parameter in search_options to enable forced search.

• false: Disables Internet search.

For billing information, see Billing.

In the Java SDK, this parameter is enableSearch. When you call over HTTP, place enable_search in the parameters object.

Enabling the Internet search feature may increase token consumption.

search_optionsobject(Optional)

The policy for web search. This parameter takes effect only if enable_search is true. For more information, see Web search.

When you call over HTTP, place search_options in the parameters object. In the Java SDK, this parameter is searchOptions.

X-DashScope-DataInspectionstring (Optional)

In addition to the content moderation capabilities of the Qwen API, this parameter specifies whether to further identify non-compliant information in the input and output content. The valid values are:

• '{"input":"cip","output":"cip"}': Performs further detection.
• Do not set this parameter: Does not further identify non-compliant information.

When you call over HTTP, place it in the request header: -H "X-DashScope-DataInspection: {\"input\": \"cip\", \"output\": \"cip\"}".

When you call with the Python SDK, configure it using headers: headers={'X-DashScope-DataInspection': '{"input":"cip","output":"cip"}'}.

For detailed usage, see Input and output AI safety guardrails.

This is not supported by the Java SDK.

This is not applicable to Qwen-Audio series models.

skillarray(Optional)

The skill parameter, which is used to enable specific generation skills, such as PPT generation. Only the qwen-doc-turbo model supports this. For more information, see Generate a PPT.

When you call over HTTP, place skill in the parameters object.

When you use skill, stream must be set to true.

Chat response object (streaming and non-streaming output formats are consistent)

status_codestring

The status code of the 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_idstring

The unique ID for this call.

The Java SDK returns the parameter as requestId.

codestring

The error code. This field is empty if the call is successful.

Only the Python SDK returns this parameter.

outputobject

The information about the call result.

usagemap

The token information for this chat request.

{
  "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, and my name is Qwen."
        }
      }
    ]
  },
  "usage": {
    "input_tokens": 22,
    "output_tokens": 17,
    "total_tokens": 39
  }
}