Skip to main content
Visual understanding

Visual reasoning

Visual reasoning models output their thinking process before answering. Use them for complex visual tasks: math problems, chart analysis, or video understanding.

Showcase

The component above is for demonstration purposes only and does not send a real request.

Supported models

  • Qwen3.8
    • Hybrid-thinking models:qwen3.8-max, qwen3.8-flash
  • Qwen3.7
    • Hybrid-thinking models:qwen3.7-plus, qwen3.7-plus-2026-05-26, qwen3.7-max-2026-06-08, qwen3.7-flash, qwen3.7-flash-2026-07-15
  • Qwen3.6
    • Hybrid-thinking models:qwen3.6-plus, qwen3.6-plus-2026-04-02, qwen3.6-flash, qwen3.6-flash-2026-04-16, qwen3.6-35b-a3b
  • Qwen3.5
    • Hybrid-thinking models:qwen3.5-plus, qwen3.5-plus-2026-02-15, qwen3.5-flash, qwen3.5-flash-2026-02-23, qwen3.5-397b-a17b, qwen3.5-122b-a10b, qwen3.5-27b, qwen3.5-35b-a3b
  • Qwen3-VL
    • Hybrid-thinking models:qwen3-vl-plus, qwen3-vl-plus-2025-12-19, qwen3-vl-plus-2025-09-23, qwen3-vl-flash, qwen3-vl-flash-2025-10-15
    • Thinking-only models:qwen3-vl-235b-a22b-thinking,qwen3-vl-32b-thinking,qwen3-vl-30b-a3b-thinking,qwen3-vl-8b-thinking
  • QVQ
    • Thinking-only models:qvq-max series, qvq-plus series
  • Kimi
    • Hybrid-thinking models:kimi-k2.6, kimi-k2.5

Usage guide

  • Thinking process: Model Studio provides two types of visual reasoning models: hybrid-thinking and thinking-only.
    • Hybrid-thinking models: Control thinking with the enable_thinking parameter:
      • Set to true: outputs thinking process first, then the final response (default for Qwen3.5 and later series).
      • Set to false: outputs response directly (default for qwen3-vl-plus, qwen3-vl-flash series).
    • Thinking-only models: These models always generate a thinking process before providing a response, and this behavior cannot be disabled.
  • Output method: Use streaming to prevent timeouts from long thinking processes.
    • Qwen3.8, Qwen3.7, Qwen3.6, Qwen3.5, Qwen3-VL, kimi-k2.6, kimi-k2.5 and stepfun/step-3.7-flash support both streaming and non-streaming methods.
    • The QVQ series supports only streaming output.
  • System prompt recommendations:
    • Single-turn/simple conversations: Do not set System Message. Pass instructions (such as role, format) through User Message for best inference results.
    • Complex applications (agents, tool calls): Use System Message to define model role, capabilities, and behavioral framework.

Getting started

Prerequisites
  • API key created and exported as an environment variable.
  • SDK users: install the latest version (DashScope Python SDK ≥1.24.6, DashScope Java SDK ≥2.21.10).
The following examples call qvq-max to solve a math problem from an image. These examples use streaming to print the thinking process and the final response separately.
  • OpenAI compatible
  • DashScope
  • Python
  • Node.js
  • HTTP
from openai import OpenAI
import os

# Initialize the OpenAI client
client = OpenAI(
    # API keys differ by region. To obtain one, see https://bailian.console.alibabacloud.com/?tab=model#/api-key
    # If not configured, replace with: api_key="sk-xxx"
    api_key = os.getenv("DASHSCOPE_API_KEY"),
    # Replace {WorkspaceId} with your workspace ID. URLs vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

reasoning_content = ""  # Define the full thinking process
answer_content = ""     # Define the full response
is_answering = False   # Check if the thinking process has ended and the response has started

# Create a chat completion request
completion = client.chat.completions.create(
    model="qvq-max",  # Example uses qvq-max. Replace with other model names as needed.
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://img.alicdn.com/imgextra/i1/O1CN01gDEY8M1W114Hi3XcN_!!6000000002727-0-tps-1024-406.jpg"
                    },
                },
                {"type": "text", "text": "How do I solve this problem?"},
            ],
        },
    ],
    stream=True,
    # Uncomment the following to return token usage in the last chunk
    # stream_options={
    #     "include_usage": True
    # }
)

print("\n" + "=" * 20 + "Thinking process" + "=" * 20 + "\n")

for chunk in completion:
    # If chunk.choices is empty, print the usage
    if not chunk.choices:
        print("\nUsage:")
        print(chunk.usage)
    else:
        delta = chunk.choices[0].delta
        # Print the thinking process
        if hasattr(delta, 'reasoning_content') and delta.reasoning_content != None:
            print(delta.reasoning_content, end='', flush=True)
            reasoning_content += delta.reasoning_content
        else:
            # Start responding
            if delta.content != "" and is_answering is False:
                print("\n" + "=" * 20 + "Full response" + "=" * 20 + "\n")
                is_answering = True
            # Print the response process
            print(delta.content, end='', flush=True)
            answer_content += delta.content

# print("=" * 20 + "Full thinking process" + "=" * 20 + "\n")
# print(reasoning_content)
# print("=" * 20 + "Full response" + "=" * 20 + "\n")
# print(answer_content)

Core capabilities

Enable or disable the thinking process

For scenarios requiring detailed thinking (problem-solving, report analysis), enable thinking mode using the enable_thinking parameter as shown below.
  • OpenAI compatible
  • DashScope
enable_thinking and thinking_budget are non-standard OpenAI parameters. The parameter passing method varies by language:
  • Python SDK: You must pass them through the extra_body dictionary.
  • Node.js SDK: You can pass them directly as top-level parameters.
import os
from openai import OpenAI

client = OpenAI(
    # API keys differ by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Replace {WorkspaceId} with your workspace ID. URLs vary by region.
    # If you are using a model in the Beijing region, replace the base_url with https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

reasoning_content = ""  # Define the full thinking process
answer_content = ""     # Define the full response
is_answering = False   # Check if the thinking process has ended and the response has started
enable_thinking = True
# Create a chat completion request
completion = client.chat.completions.create(
    model="qwen3.5-plus",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://img.alicdn.com/imgextra/i1/O1CN01gDEY8M1W114Hi3XcN_!!6000000002727-0-tps-1024-406.jpg"
                    },
                },
                {"type": "text", "text": "How do I solve this problem?"},
            ],
        },
    ],
    stream=True,
    # The enable_thinking parameter enables the thinking process. The thinking_budget parameter sets the maximum number of tokens for the reasoning process.
    # For qwen3.5-plus, qwen3-vl-plus, and qwen3-vl-flash, you can use enable_thinking to enable or disable thinking (qwen3.5-plus is enabled by default). For models with the 'thinking' suffix, such as qwen3-vl-235b-a22b-thinking, enable_thinking can only be set to true. This parameter does not apply to other Qwen-VL models.
    extra_body={
        'enable_thinking': enable_thinking
        },

    # Uncomment the following to return token usage in the last chunk
    # stream_options={
    #     "include_usage": True
    # }
)

if enable_thinking:
    print("\n" + "=" * 20 + "Thinking process" + "=" * 20 + "\n")

for chunk in completion:
    # If chunk.choices is empty, print the usage
    if not chunk.choices:
        print("\nUsage:")
        print(chunk.usage)
    else:
        delta = chunk.choices[0].delta
        # Print the thinking process
        if hasattr(delta, 'reasoning_content') and delta.reasoning_content != None:
            print(delta.reasoning_content, end='', flush=True)
            reasoning_content += delta.reasoning_content
        else:
            # Start responding
            if delta.content != "" and is_answering is False:
                print("\n" + "=" * 20 + "Full response" + "=" * 20 + "\n")
                is_answering = True
            # Print the response process
            print(delta.content, end='', flush=True)
            answer_content += delta.content

# print("=" * 20 + "Full thinking process" + "=" * 20 + "\n")
# print(reasoning_content)
# print("=" * 20 + "Full response" + "=" * 20 + "\n")
# print(answer_content)

Limit thinking length

Use the thinking_budget parameter to limit thinking process token length. If exceeded, the content is truncated and the model immediately generates the final answer. The default value is the model's maximum chain-of-thought length. For more information, see Model list.
The thinking_budget parameter is supported by Qwen3.8, Qwen3.7, Qwen3.6, Qwen3.5, Qwen3-VL (thinking mode), kimi-k2.5 (thinking mode) and kimi-k2.6 (thinking mode) .
  • OpenAI compatible
  • DashScope
thinking_budget is a non-standard OpenAI parameter. When using the OpenAI Python SDK, pass it through extra_body.
import os
from openai import OpenAI

client = OpenAI(
    # API keys differ by region. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Replace {WorkspaceId} with your workspace ID. URLs vary by region.
    # If you are using a model in the Beijing region, replace the base_url with https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

reasoning_content = ""  # Define the full thinking process
answer_content = ""     # Define the full response
is_answering = False   # Check if the thinking process has ended and the response has started
enable_thinking = True
# Create a chat completion request
completion = client.chat.completions.create(
    model="qwen3.5-plus",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://img.alicdn.com/imgextra/i1/O1CN01gDEY8M1W114Hi3XcN_!!6000000002727-0-tps-1024-406.jpg"
                    },
                },
                {"type": "text", "text": "How do I solve this problem?"},
            ],
        },
    ],
    stream=True,
    # The enable_thinking parameter enables the thinking process. The thinking_budget parameter sets the maximum number of tokens for the reasoning process.
    # For qwen3.5-plus, qwen3-vl-plus, and qwen3-vl-flash, you can use enable_thinking to enable or disable thinking (qwen3.5-plus is enabled by default). For models with the 'thinking' suffix, such as qwen3-vl-235b-a22b-thinking, enable_thinking can only be set to true. This parameter does not apply to other Qwen-VL models.
    extra_body={
        'enable_thinking': enable_thinking,
        "thinking_budget": 81920},

    # Uncomment the following to return token usage in the last chunk
    # stream_options={
    #     "include_usage": True
    # }
)

if enable_thinking:
    print("\n" + "=" * 20 + "Thinking process" + "=" * 20 + "\n")

for chunk in completion:
    # If chunk.choices is empty, print the usage
    if not chunk.choices:
        print("\nUsage:")
        print(chunk.usage)
    else:
        delta = chunk.choices[0].delta
        # Print the thinking process
        if hasattr(delta, 'reasoning_content') and delta.reasoning_content != None:
            print(delta.reasoning_content, end='', flush=True)
            reasoning_content += delta.reasoning_content
        else:
            # Start responding
            if delta.content != "" and is_answering is False:
                print("\n" + "=" * 20 + "Full response" + "=" * 20 + "\n")
                is_answering = True
            # Print the response process
            print(delta.content, end='', flush=True)
            answer_content += delta.content

# print("=" * 20 + "Full thinking process" + "=" * 20 + "\n")
# print(reasoning_content)
# print("=" * 20 + "Full response" + "=" * 20 + "\n")
# print(answer_content)

More examples

Visual reasoning models support all visual understanding features for complex scenarios such as:

Billing

Total cost = (Input tokens × Input price per token) + (Output tokens × Output price per token).
  • Thinking process (reasoning_content) is billed as output tokens. If there is no thinking output, the non-thinking mode price applies.
  • For token calculation for images/videos, see Image and video understanding.

API reference

For the input and output parameters, see Text Generation.

Error codes

If the model call fails and returns an error message, see Error codes for resolution.
Token Plan
Model Playground
Statistics and Monitoring
Support