Skip to main content

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
  • Kimi
    • Hybrid-thinking models:kimi-k2.6, kimi-k2.5
  • Stepfun
    • Hybrid-thinking model:stepfun/step-3.7-flash
  • MiniMax
    • Hybrid-thinking model:MiniMax/MiniMax-M3

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 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, stepfun/step-3.7-flash and stepfun/step-5-preview 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 The following examples call qwen3-vl-plus 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(
    # If not configured, replace with: api_key="sk-xxx"
    api_key = os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.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="qwen3-vl-plus",  # Example uses qwen3-vl-plus. 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.
from openai import OpenAI
import os

# Initialize the OpenAI client
client = OpenAI(
    # If you have not configured an environment variable, replace the following line with your Alibaba Cloud Model Studio API key: api_key="sk-xxx",
    # API keys differ by region. To obtain an API key, see https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the base URL for the Beijing region. If you are using a model in the US (Virginia) region, replace the base_url with https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
    # The URL below is for the China (Beijing) region. URLs vary by region.
    base_url="https://{WorkspaceId}.cn-beijing.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 and qwen3-vl-plus, you can use enable_thinking to enable or disable thinking (qwen3.5-plus is enabled by default). 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.
from openai import OpenAI
import os

# Initialize the OpenAI client
client = OpenAI(
    # If you have not configured an environment variable, replace the following line with your Alibaba Cloud Model Studio API key: api_key="sk-xxx",
    # API keys differ by region. To obtain an API key, see https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the base URL for the Beijing region. If you are using a model in the US (Virginia) region, replace the base_url with https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
    # The URL below is for the China (Beijing) region. URLs vary by region.
    base_url="https://{WorkspaceId}.cn-beijing.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 and qwen3-vl-plus, you can use enable_thinking to enable or disable thinking (qwen3.5-plus is enabled by default). 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
Fine-tuning
Model Compression
Statistics and Monitoring
Support
Visual reasoning - 阿里云百炼