How to Use the Qwen4-Max API

The Qwen4-Max API is live at $1.50/$4.50 per million tokens. Here's how to get a key, pick the base URL, stream thinking, send images, call tools, force JSON, cache prompts and use the Anthropic route, plus limits and errors.

INEZA Felin-Michel

INEZA Felin-Michel

16 November 2026

How to Use the Qwen4-Max API

Apidog for Enterprise

On-Premises Deploy

SSO & RBAC

SOC 2 Compliant

Explore Apidog Enterprise

The Qwen4-Max API is live on QwenCloud as a pay-per-token model with the ID qwen4-max. Create a pay-as-you-go key in your region, point the OpenAI SDK at https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1 (Singapore), and call it. It costs $1.50 per million input tokens and $4.50 per million output tokens, with a 1M-token context.

This guide covers the key, base URLs, thinking, vision, tools, structured outputs, caching, the Anthropic route, limits and errors. Every snippet follows the QwenCloud docs as read on November 16, 2026.

For background, read what Qwen4-Max is. For subscription access instead of pay-per-token, see every way to use Qwen4-Max and the Token Plan guide.

What the Qwen4-Max API gives you

The Qwen4-Max API is Alibaba’s flagship model served over QwenCloud with OpenAI-compatible, Anthropic-compatible and DashScope endpoints. It takes text, image and video input, returns text, thinks before answering by default, and supports function calling, structured outputs, context caching, batch jobs, web search and fine-tuning.

Here are the numbers from the qwen4-max model page:

Item Value
Model ID qwen4-max
Input price $1.50 per 1M tokens
Output price $4.50 per 1M tokens
Implicit cache input / explicit cache read $0.075 per 1M tokens
Explicit cache creation $1.875 (5-minute) or $3 (1-hour) per 1M tokens
Context window 1M tokens
Max input 991K (983K with thinking)
Max output 393K
Max reasoning 262K
Throughput 5,000,000 TPM

Thinking tokens bill as output tokens. For a full cost breakdown, see the Qwen4-Max pricing guide.

Get a key and pick the right base URL

Keys are tied to a region, and the key type has to match the endpoint.

  1. Open the QwenCloud console and choose a region in the upper-right selector.
  2. Go to API Keys, click Create API key, add a description and click Generate Key.
  3. Copy the key right away. It’s shown once. New pay-as-you-go keys start with sk-ws-.
  4. Export it: export DASHSCOPE_API_KEY="sk-ws-...".

Every region uses the domain {region}.maas.qwencloudapi.com. Singapore is ap-southeast-1; Frankfurt is eu-central-1, Tokyo is ap-northeast-1 and US (Virginia) is us-east-1. Then append the protocol path:

Protocol Base URL (Singapore)
OpenAI compatible (Chat Completions, Responses) https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1
Anthropic compatible https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic
DashScope HTTP https://ap-southeast-1.maas.qwencloudapi.com/api/v1
Diagram of one pay-as-you-go qwen4-max key reaching the Singapore domain, which serves three paths: /compatible-mode/v1 for the OpenAI SDK, /apps/anthropic for the Anthropic SDK and /api/v1 for DashScope

A Token Plan key (sk-sp-) only works on token-plan.maas.qwencloudapi.com, and a pay-as-you-go key only on its own region’s domain. Mixing them causes a 401. See regions and endpoints.

Your first Qwen4-Max API call

Install the OpenAI SDK (pip install openai) and run the quickstart from the docs:

import os
from openai import OpenAI

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="qwen4-max",
  messages=[{"role": "user", "content": "Summarize the benefits of solar energy in three bullet points."}]
)
print(completion.choices[0].message.content)

Thinking is on by default for qwen4-max, so this call also spends reasoning tokens. For long prompts, stream or set a client timeout of 180 seconds or more.

Thinking mode and streaming reasoning_content

Qwen4-Max is a hybrid thinking model. The documented defaults are enable_thinking=true, reasoning_effort=high and thinking_budget=131072. Effort levels are low, high and xhigh; none turns thinking off.

Stream reasoning and answer as two phases (adapted from the model page sample):

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1",
)
messages = [{"role": "user", "content": "Who are you"}]
completion = client.chat.completions.create(
    model="qwen4-max",
    messages=messages,
    extra_body={"enable_thinking": True},
    stream=True
)
for chunk in completion:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        print(delta.reasoning_content, end="", flush=True)  # phase 1: thinking
    if delta.content:
        print(delta.content, end="", flush=True)            # phase 2: answer

Three rules:

To skip thinking, pass {"enable_thinking": False}.

Image and video input

Send images as image_url parts and videos as video_url parts. This mirrors the docs’ vision sample with the model set to qwen4-max:

completion = client.chat.completions.create(
  model="qwen4-max",
  messages=[{
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/invoice.jpg"}},
      {"type": "text", "text": "Describe what you see in this image"},
    ],
  }],
)

For video, use {"type": "video_url", "video_url": {"url": "..."}, "fps": 2}. Local files go in as Base64 Data URIs.

The vision guide allows up to 2,048 URL images at 20 MB each, 250 Base64 images, and 64 MB per request. Image detail defaults to high, which costs more input tokens.

Function calling

Pass a tools array like any OpenAI-compatible model:

tools = [{
  "type": "function",
  "function": {
    "name": "get_current_weather",
    "description": "Useful when you want to check the weather for a specific city.",
    "parameters": {
      "type": "object",
      "properties": {"location": {"type": "string", "description": "City or county, such as Singapore or New York."}},
      "required": ["location"],
    },
  },
}]
completion = client.chat.completions.create(model="qwen4-max", messages=messages, tools=tools)

Read message.tool_calls, run the function, append a tool message and call again.

In thinking mode, tool_choice only accepts "auto" or "none"; to force a function, disable thinking first. With thinking on, send reasoning_content back with tool results, or accuracy drops.

Structured outputs

qwen4-max supports strict JSON Schema mode:

completion = client.chat.completions.create(
  model="qwen4-max",
  messages=[{"role": "user", "content": "Extract the name and age: Ana is 31."}],
  response_format={
    "type": "json_schema",
    "json_schema": {
      "name": "user_info",
      "strict": True,
      "schema": {
        "type": "object",
        "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
        "required": ["name", "age"],
        "additionalProperties": False,
      },
    },
  },
)

With the looser {"type": "json_object"} mode, the word “JSON” must appear in a message or the API rejects the request. Image or video input falls back to json_object, so the schema isn’t enforced on multimodal calls.

Context cache and batch

Cache. With no settings, the implicit cache matches prefixes but doesn’t guarantee hits. For deterministic hits, use the Qwen4 explicit cache: mark a content block with "prompt_cache_breakpoint": {"mode": "explicit"} (the message content must be an array), and set the TTL with extra_body={"prompt_cache_options": {"mode": "explicit", "ttl": "5m"}}. TTL is 5m or 1h, and the cached prefix needs at least 1,024 tokens. Reads cost $0.075 per million tokens, 95% less than fresh input.

Batch. The batch guide bills input and output at 50% of the real-time price and returns results within 24 hours. For qwen4-max, Batch File runs in one region outside Singapore and doesn’t support context caching, so check the batch guide before you plan a pipeline around it.

The Anthropic-compatible route

Already built on the Anthropic SDK? Change the base URL and key:

import anthropic
import os

client = anthropic.Anthropic(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic",
)
message = client.messages.create(
    model="qwen4-max",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Who are you?"}],
    thinking={"type": "disabled"},
)
print(message.content)

This sample turns thinking off, as the docs’ own sample does. End the base URL at /apps/anthropic. Adding /v1/ produces /v1/v1/... and a 404. Thinking is on by default here too, and with thinking enabled max_tokens must exceed the thinking budget. Effort uses output_config.effort (low, high, xhigh), and the built-in web_search and web_fetch tools are available on this route.

Qwen4-Max API rate limits

From the rate limits page:

Region RPM TPM
Singapore Dynamic Dynamic tiers: 5M, 10M, 20M
Frankfurt, Tokyo, US (Virginia) and other Global-scope regions 30,000 5,000,000

Limits apply per account per region and also per second (RPS = RPM / 60), so a burst can throttle you under the per-minute total.

The free quota page says free quota exists only in Singapore, is per model (typically 1,000,000 tokens), lasts 90 days and needs payment details on file. It doesn’t name qwen4-max, so check the Free Tier page in the console, or read how to use Qwen4-Max for free.

Common Qwen4-Max API errors

Code What it means Fix
401 InvalidApiKey Key and base URL are from different regions, or a Token Plan key hit a pay-as-you-go endpoint Use a key created in the same region as the URL
400 InvalidParameter Often max_tokens outside 1 to 32,768 with thinking on Switch to max_completion_tokens
403 AllocationQuota.FreeTierOnly Free quota used up before payment setup Add payment details on the Free Tier page
404 ModelNotFound qwen4-max isn’t offered in the region you called Check Model prices for that region
429 Throttling RPM or TPM limit reached Back off and retry, or spread load across seconds

Let your coding agent test the Qwen4-Max API with Apidog CLI

Your coding agent writes the integration, so let it write the regression test too. Apidog CLI lets it save the endpoint, store the key and run assertions.

Flow from one prompt to a coding agent, which runs apidog environment create, endpoint create, test-case create with assertions on status, choices, usage and reasoning_content, then apidog run for a pass or fail report

Set it up once:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Then give your agent one prompt:

In Apidog project <projectId>, create an environment "Qwen Singapore" with base URL
https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1 and a secret
variable DASHSCOPE_API_KEY. Add POST /chat/completions with a Bearer auth header,
model qwen4-max and enable_thinking true. Create a test case asserting status 200,
a non-empty choices array, a usage object, and reasoning_content present on the
first choice's message. Run it and summarize any failures.

The agent reads each payload schema before it writes, then runs the case:

apidog environment create "Qwen Singapore" --project <projectId> --base-url https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1
apidog cli-schema get environment-update
apidog environment update <envId> --project <projectId> --file env.json
apidog cli-schema get endpoint-create
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

The cli reporter prints pass or fail; json writes a report the agent reads. Move the same apidog run ... -r junit into CI with the Apidog CLI CI/CD guide, and see Apidog CLI in Claude Code for more prompts. Apidog’s Free plan covers up to 4 users.

FAQ

What is the Qwen4-Max API model ID?

The stable ID is qwen4-max. The earlier qwen4-max-preview ID was for the Token Plan only during the preview that began on November 11, 2026.

Is the Qwen4-Max API OpenAI compatible?

Yes. Use the OpenAI SDK with the /compatible-mode/v1 base URL for Chat Completions and the Responses API. An Anthropic-compatible endpoint and the DashScope API are also available.

How do I turn off thinking in the Qwen4-Max API?

Pass extra_body={"enable_thinking": False}. You lose reasoning_content, but latency and output tokens drop. Comparing models? See Qwen4-Max vs Qwen3.8.

How much does the Qwen4-Max API cost?

$1.50 per million input tokens and $4.50 per million output tokens, with cached reads at $0.075 per million.

Can I use my Token Plan key with the pay-per-token API?

No. Token Plan keys (sk-sp-) only work on token-plan.maas.qwencloudapi.com, and pay-as-you-go keys only work on their own region’s domain.

Explore more

How to Normalize Data From 84 APIs Into One Schema (And Contract-Test It)

How to Normalize Data From 84 APIs Into One Schema (And Contract-Test It)

Normalizing reviews from 84 platforms, 59 with an official API and 25 without: one schema, stable IDs, deduplication and contract tests against an OpenAPI spec.

16 November 2026

How to Use Qwen4-Max for Free: 1M API Tokens and 3 Other Routes

How to Use Qwen4-Max for Free: 1M API Tokens and 3 Other Routes

Qwen4-Max has a 1M-token free quota on QwenCloud's Singapore API. Here's how to claim it without surprise charges, how far it goes, the softer free routes (Qoder, QwenWork, QwenStudio) and when the paid API is cheaper.

16 November 2026

Qwen4-Max Benchmarks: Work360, Terminal-Bench 4.0 and What the Scores Mean

Qwen4-Max Benchmarks: Work360, Terminal-Bench 4.0 and What the Scores Mean

Qwen4-Max beats Qwen3.8-Max on every shared benchmark and leads 4 of 16 overall, but 10 of those scores are Alibaba's own runs. Here's every number, who ran it, and how to run your own check.

16 November 2026

Practice API Design-first in Apidog

Discover an easier way to build and use APIs

How to Use the Qwen4-Max API