Alibaba released Qwen4-Max on 16 November 2026. It is the first model in the new Qwen4 family. It combines reasoning, native vision and a one-million-token context window, and you can call it today through QwenCloud’s OpenAI-compatible API. This guide covers the official specs, how to make your first request from Python, and the settings that change cost and speed: thinking, reasoning effort and caching.

What Qwen4-Max is

According to Alibaba’s launch announcement, Qwen4-Max is a sparse Mixture-of-Experts model with 2.4 trillion total parameters, of which 71 billion are active for each token. Alibaba says it is aimed at coding, agentic tasks and visual reasoning, and that it ranked 6th on the Code Arena coding leaderboard at launch. Alibaba also says that on its own Work360 benchmark it beats Qwen3.8-Max while using 35% fewer tokens at high reasoning effort. Treat vendor benchmarks as a starting point, not a verdict. Run your own prompts before you switch production traffic.

The QwenCloud model page lists the details developers need:

Item Value
Model ID qwen4-max
Context length 1,000,000 tokens
Max output (non-thinking) 131,072 tokens
Max thinking + final answer 262,144 tokens
Default thinking budget 131,072 tokens
Batch inference Not supported

Supported features include function calling, structured output, image, video and PDF understanding, web search, a code interpreter (thinking must be on), MCP, streaming, parallel tool calls and implicit caching. Fine-tuning and custom deployment are not offered.

Where you can call it

The docs list Singapore (International), China North 2 (Beijing), and a Global deployment covering Frankfurt, Hong Kong, Tokyo and US (Virginia). Beijing and Global share one price list, and Singapore has its own. Check the official pricing page before you estimate costs, because input, output and cache rates differ by region.

Step 1: Get a key and install the SDK

Create an API key in QwenCloud and export it:

export DASHSCOPE_API_KEY="sk-..."
pip install --upgrade openai

Qwen4-Max supports the OpenAI Chat Completions and Responses formats, the Anthropic Messages format and the native DashScope API. The examples below use Chat Completions with the official openai Python package, because most existing code already speaks that format.

Step 2: Your first request

import os
from openai import OpenAI

# Singapore endpoint. For another region, change ap-southeast-1 in the URL.
client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1",
)

response = client.chat.completions.create(
    model="qwen4-max",
    messages=[
        {"role": "system", "content": "You are a senior Python reviewer."},
        {"role": "user", "content": "List three risks in using global state in a FastAPI app."},
    ],
)
print(response.choices[0].message.content)
print(response.usage)

Always print response.usage while you test. Thinking is on by default, so a short answer can still use a lot of reasoning tokens.

Step 3: Control thinking and reasoning effort

The defaults are enable_thinking=true, reasoning_effort="high" and thinking_budget=131072. Qwen4-Max accepts three effort levels: low, high and xhigh. If you send OpenAI-style values, QwenCloud maps them: minimal becomes low, medium becomes high and max becomes xhigh.

For simple tasks such as classification, rewriting or extraction, turn thinking off. enable_thinking is not a standard OpenAI parameter, so pass it through extra_body:

fast = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": "Classify this ticket: 'Refund not received'. Reply with one word."}],
    extra_body={"enable_thinking": False},
)
print(fast.choices[0].message.content)

For hard tasks, keep thinking on and pick the effort level:

deep = client.chat.completions.create(
    model="qwen4-max",
    reasoning_effort="xhigh",
    messages=[{"role": "user", "content": "Design a migration plan from MySQL 5.7 to 8.4 with zero downtime."}],
)

max_completion_tokens limits thinking and the final answer together. It can go up to 262,144 tokens with thinking on and 131,072 with thinking off. Set it on purpose so one runaway request can’t burn your budget.

Default sampling also changes with the mode. Temperature is 1.0 with thinking on and 0.7 with it off. presence_penalty is 0.0 with thinking and 1.5 without. If you copy settings over from another model, check these first, because they change how the output reads.

Step 4: Streaming for chat UIs

stream = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": "Explain Python's GIL in 5 bullet points."}],
    stream=True,
    extra_body={"enable_thinking": False},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Step 5: Tool calls in agent loops

Function calling works like other OpenAI-compatible models. One rule matters here. preserve_thinking is on by default, and the docs ask you to keep the assistant messages and their reasoning when you send tool results back in multi-turn tool calls. If you strip the assistant turn and only send the tool result, the model loses its plan.

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up an order by ID",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

messages = [{"role": "user", "content": "Where is order A-1042?"}]
first = client.chat.completions.create(model="qwen4-max", messages=messages, tools=tools)
msg = first.choices[0].message
messages.append(msg)  # keep the assistant turn exactly as returned

for call in msg.tool_calls or []:
    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": '{"status": "shipped", "eta": "2026-11-19"}',
    })

final = client.chat.completions.create(model="qwen4-max", messages=messages, tools=tools)
print(final.choices[0].message.content)

Cut costs with explicit caching

Qwen4 adds an explicit cache. You mark reusable prefixes, such as a long system prompt, tool definitions or a reference document, and a matching prefix can then be reused reliably while the cache is valid. TTL options are 5m (the default) and 1h. Implicit caching still exists, but the docs note it does not guarantee hits. Explicit caching works with Chat Completions, Responses and Anthropic Messages, but not with the native DashScope API. The exact request fields are in the “Explicit cache (Qwen4)” page linked from the model docs.

Practical tip: put stable content first (system prompt, tools, documents) and the changing user question last. Every caching scheme rewards that layout.

CoT Summary for showing reasoning

If your product shows “how the model thought”, turn on CoT Summary. It returns a readable summary plus the full reasoning in encrypted form. Show the summary, and send the encrypted content back unchanged in later turns so the model keeps its reasoning history. The docs warn that summaries can sometimes be missing, so your UI should handle that case.

Should you switch?

  • Long-document and multimodal work: a 1M-token context plus native image, video and PDF input makes it a strong candidate.
  • Agents: tool calling, MCP and long-horizon planning are the main focus of the launch.
  • Cost-sensitive tasks: turn thinking off or use low effort, and measure tokens per task, not just price per token.
  • Batch jobs: batch inference is not supported, so look elsewhere for large offline runs.

Takeaway

Qwen4-Max is a drop-in for most OpenAI-compatible code. Change base_url and model and you are running. The real tuning is in thinking: switch it off for simple calls, choose low, high or xhigh for hard ones, cap max_completion_tokens, and keep assistant turns intact in tool loops. Start with the official Qwen4-Max docs and test it on your own workload before moving traffic.