> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwencloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Thinking

> Solve complex tasks with step-by-step thinking

Thinking (reasoning) models reason before answering — outputting `reasoning_content` (Chat Completions / DashScope) or `reasoning_text` events (Responses API). Models support thinking in one of two modes:

- **Hybrid**: toggle thinking on or off per request with `enable_thinking`.
- **Thinking-only** (such as glm-5.3, kimi-k2.7-code): always thinks — cannot be disabled.

## Supported models

Availability differs by region. For the regions of each model, see [Text generation models](/developer-guides/getting-started/text-generation-models) and [Regions and endpoints](/developer-guides/getting-started/regions).

<Accordion title="Expand the full model list">
  ### Qwen4.0

  `qwen4-max`: hybrid thinking mode, enabled by default.

  ### Qwen3.8

  - **Max series** (hybrid, thinking enabled by default): `qwen3.8-max`, `qwen3.8-max-0902`
  - **Flash series** (hybrid, thinking enabled by default): `qwen3.8-flash`
  - **Open-source series** (hybrid, thinking enabled by default): `qwen3.8-27b`
  - **Open-source series** (thinking-only): `qwen3.8-2.4t-a95b`
  - **Omni series** (hybrid, thinking enabled by default): `qwen3.8-omni-flash`. Adjust thinking effort with `reasoning_effort`.

  ### Qwen3.7

  - **Max series** (hybrid, thinking enabled by default): `qwen3.7-max`, `qwen3.7-max-2026-05-20`, `qwen3.7-max-2026-06-08`
  - **Max series** (thinking-only, Singapore only): `qwen3.7-max-preview`, `qwen3.7-max-2026-05-17`
  - **Plus series** (hybrid, thinking enabled by default): `qwen3.7-plus`, `qwen3.7-plus-2026-05-26`
  - **Flash series** (hybrid, thinking enabled by default): `qwen3.7-flash`, `qwen3.7-flash-2026-07-15`

  ### Qwen3.6

  - **Plus series** (hybrid, thinking enabled by default): `qwen3.6-plus`, `qwen3.6-plus-2026-04-02`
  - **Flash series** (hybrid, thinking enabled by default): `qwen3.6-flash`, `qwen3.6-flash-2026-04-16`
  - **Open-source edition**: `qwen3.6-35b-a3b`

  ### Qwen3.5

  - **Plus series** (hybrid, thinking enabled by default): `qwen3.5-plus`, `qwen3.5-plus-2026-02-15`
  - **Flash series** (hybrid, thinking enabled by default): `qwen3.5-flash`, `qwen3.5-flash-2026-02-23`

  ### Qwen3

  - **Plus series** (hybrid, thinking disabled by default): `qwen-plus`, `qwen-plus-latest`, `qwen-plus-2025-04-28` and later snapshots
  - **Flash series** (hybrid, thinking disabled by default): `qwen-flash`, `qwen-flash-2025-07-28` and later snapshots

  ### DeepSeek

  - `deepseek-v4.1-flash-1017` supports thinking.
  - Hybrid, thinking enabled by default: `deepseek-v4.1-flash`, `deepseek-v4-pro`

  ### GLM

  - Thinking-only: `glm-5.3`
  - Hybrid, thinking enabled by default: `glm-5.2`, `glm-5.2-fast-preview`, `glm-5.1`, `glm-5` (China North 2 (Beijing) only)

  ### Kimi

  - Thinking-only: `kimi-k2.7-code`
  - Hybrid, thinking enabled by default: `kimi-k3.1-pro`, `kimi-k3`
  - Hybrid, thinking disabled by default: `kimi-k2.6` (China North 2 (Beijing) only), `kimi-k2.5`

  ### MiniMax

  - Thinking-only: `MiniMax-M2.5` (China North 2 (Beijing) only)
</Accordion>

## Enable thinking

<Tabs>
  <Tab title="OpenAI Chat Completions">
    <CodeGroup>
      ```python Python {8}
      import os
      from openai import OpenAI
      # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
      # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
      client = OpenAI(api_key=os.getenv("DASHSCOPE_API_KEY"), base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1")

      completion = client.chat.completions.create(
        model="qwen3.8-max",
        messages=[{"role": "user", "content": "If 3x + 7 = 22, what is x?"}],
        extra_body={"enable_thinking": True},              # ← enable thinking
        stream=True,
      )
      for chunk in completion:
        if not chunk.choices:
          continue
        delta = chunk.choices[0].delta
        if hasattr(delta, "reasoning_content") and delta.reasoning_content:
          print(delta.reasoning_content, end="", flush=True)  # ← phase 1: thinking
        if hasattr(delta, "content") and delta.content:
          print(delta.content, end="", flush=True)             # ← phase 2: answer
      ```

      ```javascript Node.js {7}
      import OpenAI from "openai";
      // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
      // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
      const client = new OpenAI({ apiKey: process.env.DASHSCOPE_API_KEY, baseURL: "https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1" });

      const stream = await client.chat.completions.create({
        model: "qwen3.8-max",
        messages: [{ role: "user", content: "If 3x + 7 = 22, what is x?" }],
        enable_thinking: true,                             // ← enable thinking
        stream: true,
      });
      for await (const chunk of stream) {
        if (!chunk.choices?.length) continue;
        const delta = chunk.choices[0].delta;
        if (delta.reasoning_content)
          process.stdout.write(delta.reasoning_content); // ← phase 1: thinking
        if (delta.content)
          process.stdout.write(delta.content);            // ← phase 2: answer
      }
      ```

      ```bash curl
      # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
      # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
      curl -X POST https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
        -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
        -H "Content-Type: application/json" --no-buffer \
        -d '{"model":"qwen3.8-max","messages":[{"role":"user","content":"If 3x + 7 = 22, what is x?"}],"stream":true,"enable_thinking":true}'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="OpenAI Responses API">
    Thinking arrives as `response.reasoning_text.delta` events, followed by `response.output_text.delta` for the answer.

    <CodeGroup>
      ```python Python {8}
      import os
      from openai import OpenAI
      # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
      # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
      client = OpenAI(api_key=os.getenv("DASHSCOPE_API_KEY"), base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1")

      stream = client.responses.create(
        model="qwen3.8-max",
        input="If 3x + 7 = 22, what is x?",
        extra_body={"enable_thinking": True},              # ← enable thinking
        stream=True,
      )
      for chunk in stream:
        if chunk.type == "response.reasoning_text.delta":
          print(chunk.delta, end="", flush=True)         # ← phase 1: thinking
        elif chunk.type == "response.output_text.delta":
          print(chunk.delta, end="", flush=True)         # ← phase 2: answer
      ```

      ```javascript Node.js {7}
      import OpenAI from "openai";
      // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
      // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
      const client = new OpenAI({ apiKey: process.env.DASHSCOPE_API_KEY, baseURL: "https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1" });

      const stream = await client.responses.create({
        model: "qwen3.8-max",
        input: "If 3x + 7 = 22, what is x?",
        enable_thinking: true,                             // ← enable thinking
        stream: true,
      });
      for await (const chunk of stream) {
        if (chunk.type === "response.reasoning_text.delta")
          process.stdout.write(chunk.delta);             // ← phase 1: thinking
        else if (chunk.type === "response.output_text.delta")
          process.stdout.write(chunk.delta);             // ← phase 2: answer
      }
      ```

      ```bash curl
      # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
      # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
      curl -X POST https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/responses \
        -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
        -H "Content-Type: application/json" --no-buffer \
        -d '{"model":"qwen3.8-max","input":"If 3x + 7 = 22, what is x?","stream":true,"enable_thinking":true}'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="DashScope">
    <CodeGroup>
      ```python Python {8,14}
      import os
      import dashscope

      # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
      # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
      client = dashscope.Client(
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        base_url="https://ap-southeast-1.maas.qwencloudapi.com/api/v1",
      )

      stream = client.multimodal.chat.create(
        model="qwen3.8-max",
        messages=[{"role": "user", "content": [{"text": "If 3x + 7 = 22, what is x?"}]}],
        enable_thinking=True,  # ← enable thinking
        stream=True,  # ← SDK 2.0 outputs incrementally by default
      )
      for chunk in stream:
        delta = chunk.choices[0].delta
        if delta.reasoning_content:
          print(delta.reasoning_content, end="", flush=True)   # ← phase 1: thinking
        if delta.content:
          print(delta.content, end="", flush=True)   # ← phase 2: answer
      ```

      ```java Java {5,15,16}
      import java.util.*;
      import com.alibaba.dashscope.aigc.multimodalconversation.*;
      import com.alibaba.dashscope.common.Role;
      import com.alibaba.dashscope.utils.Constants;
      // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
      // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
      Constants.baseHttpApiUrl = "https://ap-southeast-1.maas.qwencloudapi.com/api/v1";

      // DashScope Java SDK 2.19.4+ required
      MultiModalMessage userMsg = MultiModalMessage.builder()
        .role(Role.USER.getValue())
        .content(List.of(Map.of("text", "If 3x + 7 = 22, what is x?")))
        .build();
      MultiModalConversationParam param = MultiModalConversationParam.builder()
        .apiKey(apiKey).model("qwen3.8-max")
        .enableThinking(true)                              // ← enable thinking
        .incrementalOutput(true)                           // ← recommended: new tokens only
        .messages(Arrays.asList(userMsg))
        .build();
      conv.streamCall(param).blockingForEach(result -> {
        var msg = result.getOutput().getChoices().get(0).getMessage();
        if (msg.getReasoningContent() != null)
          System.out.print(msg.getReasoningContent());   // ← phase 1: thinking
        if (msg.getContent() != null && !msg.getContent().isEmpty())
          System.out.print(msg.getContent().get(0).get("text"));  // ← phase 2
      });
      ```

      ```bash curl
      # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
      # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
      curl -X POST "https://ap-southeast-1.maas.qwencloudapi.com/api/v1/services/aigc/multimodal-generation/generation" \
        -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
        -H "Content-Type: application/json" \
        -H "X-DashScope-SSE: enable" \
        -d '{"model":"qwen3.8-max","input":{"messages":[{"role":"user","content":[{"text":"If 3x + 7 = 22, what is x?"}]}]},"parameters":{"enable_thinking":true,"incremental_output":true}}'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Note>
  When thinking mode is enabled (`enable_thinking` is `true`), the valid range for the `max_tokens` parameter is `[1, 32768]`. Values outside this range return a 400 error (`InvalidParameter: Range of max_tokens should be [1, 32768]`). Non-thinking mode has no such limit.

  We recommend using `max_completion_tokens` instead of `max_tokens`: `max_completion_tokens` limits the model's complete output (including the chain of thought and final reply) and is not subject to the 32768 cap; `max_tokens` only limits the final reply portion and is being deprecated. New integrations should use `max_completion_tokens`.
</Note>

```python
# When thinking mode is enabled, use max_completion_tokens to limit output length
completion = client.chat.completions.create(
  model="qwen3.8-max",
  messages=[{"role": "user", "content": "Who are you?"}],
  extra_body={"enable_thinking": True},
  # max_completion_tokens limits the total output length (chain of thought + reply), no 32768 cap
  max_completion_tokens=65536,
)
```

## Control thinking depth

### Token budget

Use `thinking_budget` to cap the number of thinking tokens. If the limit is reached, the model stops thinking and generates its answer immediately. Supported by Qwen4.0, Qwen3.8, Qwen3.7, Qwen3.6, Qwen3.5, Qwen3-VL, Qwen3, GLM, and Kimi series models, and the Qwen3.8 open-source series, except `kimi-k3.1-pro` and `kimi-k3`, which do not support this parameter. Chat Completions and DashScope only — not supported by the Responses API.

<Tabs>
  <Tab title="OpenAI Chat Completions">
    ```python
    extra_body={"enable_thinking": True, "thinking_budget": 500}
    ```
  </Tab>

  <Tab title="DashScope">
    ```python
    enable_thinking=True,
    thinking_budget=500,
    ```
  </Tab>
</Tabs>

### reasoning\_effort

Use `reasoning_effort` to control thinking intensity by level instead of specifying a token count. Supported values and defaults vary by model. Example with `qwen3.8-max` (options: `low`, `medium`, `xhigh`; default `xhigh`):

<Tabs>
  <Tab title="OpenAI Chat Completions">
    ```python
    extra_body={"enable_thinking": True, "reasoning_effort": "medium"}
    ```
  </Tab>

  <Tab title="DashScope">
    ```python
    enable_thinking=True,
    reasoning_effort="medium",
    ```
  </Tab>
</Tabs>

<Warning>
  `qwen4-max-preview` ([Token Plan only](/token-plan/overview)), `qwen3.8-max` does not support setting `reasoning_effort` and `thinking_budget` simultaneously — doing so returns an error. When neither is set, the model uses its default.
</Warning>

<Note>
  This is not an OpenAI standard parameter. When using the Python SDK, pass it via `extra_body`. For supported levels, defaults, and the mapping between `reasoning_effort` and `thinking_budget` for each model, see the [API Reference](/api-reference/chat/openai-chat).
</Note>

### Experience deep thinking in the console

1. Log on to the QwenCloud console.
2. In the left-side navigation pane, choose **Playground** > **Text models** to open the model experience center.
3. The Qwen3.7-Max model is displayed by default. You can also click the model name to select other Qwen3 series models from the dropdown list.
4. Click **Deep Thinking** at the bottom of the input box to enable reasoning mode and view the model's thinking process.
5. Switch to the **Model Debugging** tab and set the `thinking_budget` parameter in the configuration panel to control the maximum number of tokens for chain-of-thought output. Value range: 1-32768, default: 4000. To try more models, visit the model marketplace.

### Prompt-level control

With `enable_thinking: true`, add `/no_think` to skip thinking for one turn. `/think` restores it. Last instruction wins. Supported by open-source Qwen3 hybrid models and `qwen-plus-2025-04-28`.

### Preserve thinking in multi-turn

`qwen4-max` enables `preserve_thinking` by default. In multi-turn conversations, return all historical thinking in the assistant messages' `reasoning_content` field. Do not concatenate it into `content`.

For models with `preserve_thinking` disabled by default, they do not read `reasoning_content` from the `messages` array in multi-turn conversations. Set `preserve_thinking` to `true` to append the `reasoning_content` in assistant messages to the next input, allowing the model to reference previous reasoning.

Supported models: `qwen4-max`, `qwen3.8-max`, `qwen3.8-max-0902`, `qwen3.8-flash`, `qwen3.8-omni-flash` (enabled by default), `qwen3.7-max`, `qwen3.7-max-2026-06-08`, `qwen3.7-max-2026-05-20`, `qwen3.7-max-preview`, `qwen3.7-max-2026-05-17`, `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`, `kimi-k2.7-code` (deployed on QwenCloud).

`kimi-k3.1-pro` and `kimi-k3` (deployed on QwenCloud) retain historical `reasoning_content` supplied by the client by default. We recommend returning historical assistant messages and their complete `reasoning_content` in multi-turn requests.

<Tabs>
  <Tab title="OpenAI Chat Completions">
    ```python
    extra_body={"enable_thinking": True, "preserve_thinking": True}
    ```

    <Note>
      `preserve_thinking` is not an OpenAI standard parameter. When using the Python SDK, pass it via `extra_body`.
    </Note>
  </Tab>

  <Tab title="DashScope">
    ```python
    enable_thinking=True,
    preserve_thinking=True,
    ```
  </Tab>
</Tabs>

## Function calling with thinking mode

When thinking is enabled during [function calling](/developer-guides/tool-calling/function-calling), the model reasons about which tools to call and how to use results before responding. The response includes `reasoning_content` before each tool call.

**Key points:**

- Pass `enable_thinking: true` alongside your `tools` array — no other config needed.
- In multi-turn tool-call flows, include the assistant's `reasoning_content` when sending tool results back. Omitting it degrades accuracy.
- Streaming delivers thinking tokens first, then tool call deltas. See [Streaming with tool calls](/developer-guides/run-and-scale/streaming#streaming-with-tool-calls) for the parse pattern.
- `thinking_budget` works the same as in regular thinking mode.

<Tip>
  Thinking mode is most valuable for complex tool orchestration — multi-step reasoning about which tools to call, parameter selection, and result interpretation. For simple single-tool calls, the overhead may not be worth it.
</Tip>

## Billing

Thinking tokens are billed as output tokens. Some hybrid thinking models have different pricing for thinking mode vs. non-thinking mode. If a model in thinking mode does not produce any thinking content, it is billed at the non-thinking mode price.

For model-specific thinking mode pricing, see [Models](https://home.qwencloud.com/models).

## Notes

- **Streaming required for some models**: Non-streaming is supported by Qwen3.7 Max, Qwen3.7 Plus, Qwen3.6 Plus, Qwen3.5 Plus/Flash, Qwen3 Max, Qwen Plus/Flash/Turbo (commercial), and Qwen3.5 open-source models. Qwen3 open-source models and the Qwen3.8 open-source series (`qwen3.8-2.4t-a95b`) require streaming. Streaming is always recommended to avoid timeout risks.
- **Qwen3.8 open source series** (hybrid thinking mode, **thinking enabled by default**): `qwen3.8-27b`
- **Qwen3.8 open source series** (**thinking mode only**): `qwen3.8-2.4t-a95b`
- **Qwen3.8 Omni series** (hybrid thinking mode, **thinking enabled by default**): `qwen3.8-omni-flash`. Configure thinking effort with `reasoning_effort`.
- **No audio output in thinking mode** (Qwen3-Omni): Text and image inputs work normally; audio output is not available when thinking is enabled.

## FAQ

**Why is `qwen3.7-plus` slow to respond, and how do I troubleshoot it?**

`qwen3.7-plus` is a hybrid thinking model with thinking mode enabled by default. The thinking process generates a large number of reasoning tokens — more than 60% of the total output tokens in measurements — so the total latency of a single call is much higher than in non-thinking mode. The token generation speed itself is normal, at about 52 to 54 tokens/s. The longer total latency comes from the number of tokens the thinking process produces, not from a slower model or a network fault.

To troubleshoot the latency:

1. Check whether thinking mode is enabled. It is enabled by default for `qwen3.7-plus`. If the response returns the `reasoning_content` field, thinking mode is active.
2. Review `completion_tokens` and `reasoning_tokens` in the usage statistics of the response. A high proportion of `reasoning_tokens` means the long total latency is expected behavior of thinking mode.
3. If you do not need the reasoning process, set `enable_thinking` to `false` in the request to disable thinking mode. This greatly reduces output tokens and lowers total latency by 60% to 75% in measurements.
4. If you want to keep the reasoning capability, use streaming output. You receive the first token sooner and can watch the reasoning in real time instead of waiting for the full response.

<Note>
  Usage statistics show the total latency of a single call, including the time spent generating reasoning tokens. This is not the generation latency of an individual token.
</Note>

**What do I do if a long prompt fails to generate a response or times out?**

If a call with a long prompt fails or times out, thinking mode (`enable_thinking=true`) is usually enabled. Thinking mode increases processing time, which can truncate the response or cause the request to time out when the prompt is long.

Solutions:

- **Disable thinking mode**: set `enable_thinking` to `false`. Processing time can drop from about 50 seconds to about 30 seconds.
- **Enable streaming output**: set `stream` to `true` to avoid the timeout limit of non-streaming mode.
- **Increase the timeout**: to keep thinking mode enabled, set the client timeout to 180 seconds or longer.

**My third-party client disconnects after the thinking tag is output. What do I do?**

This is a client-side issue, not a platform restriction on exposing the thinking process. QwenCloud uses the `enable_thinking` parameter to toggle thinking mode, and the `reasoning_content` field in the response contains the full thinking process, so the model returns the thinking content as expected. The disconnection is usually caused by unstable client network conditions or client version compatibility issues.

Troubleshooting steps:

- Check the stability of the client's network connection.
- Upgrade the client to the latest version.
- Review the client logs to correlate the disconnection timestamp with the thinking tag output.

You can also call the model directly through the DashScope API to verify that the thinking capability works as expected.

## Qwen4-Max thinking configuration

Defaults: `enable_thinking=true`, `preserve_thinking=true`, `reasoning_effort=high`, `thinking_budget=131072`. `minimal`/`low` map to `low`, `medium`/`high` to `high`, `xhigh`/`max` to `xhigh`; `none` disables thinking. Effort alone retains the 131072 budget. Budget alone maps 1–4096 to `low`, 4097–131072 to `high`, 131073–262144 to `xhigh`, while retaining the supplied budget. Thinking and the final answer share an output budget of up to 262144 tokens.

Responses uses `reasoning.effort`. Anthropic uses `output_config.effort`: `low`, `high` (default), `xhigh`; `medium` maps to `high`, `max` to `xhigh`.

To display summaries and restore historical reasoning, use [Thinking summary and encryption](/developer-guides/text-generation/cot-summary)。
