Qwen4-Max API: connect the released model and migrate from preview

Use the correct Qwen4-Max model ID, region and billing route. Check output limits, tool history and a first response before migrating an agent.

A folding bridge forms a continuous span for a small orange vehicle, illustrating a checked migration path.

Qwen4-Max is now documented as a released model with the API identifier qwen4-max. It is distinct from qwen4-max-preview. If an older article says Qwen4 is available only through a preview subscription, check the current official documentation before configuring your application.

This guide was checked on November 16, 2026. It uses QwenCloud’s direct API, explains the migration decisions, and supplies a small response validator. We checked documentation and local synthetic response cases; we have not made a paid Qwen4 call or benchmarked the model for this article. Examples below are requests to run and acceptance criteria, not measured performance claims.

What changed, and which model should you select?

The official model page now describes qwen4-max, while preview material refers to a different identifier. Use the exact name available on the route you intend to call. Do not add a provider prefix from an unrelated gateway or assume that a client display label is the API ID.

The released model documents text generation, image and video understanding, tool calling and structured output. A useful distinction for office workflows: understanding an image does not mean generating an image, and a model returning slide content does not by itself create an editable presentation file. File creation, execution and delivery require appropriate tools and a harness that checks their results.

DecisionWhat to check before changing your configuration
Released model versus previewSelect qwen4-max for this guide; keep preview configuration separate
Direct API versus a gatewayVerify that exact provider’s catalog, credentials and protocols
Pay-as-you-go versus Token PlanUse the endpoint and key associated with that billing route
RegionMatch the console region, key and endpoint
Agent migrationValidate a completed task and its artifacts, not just a successful HTTP request

The official context limit is 1,000,000 tokens. The released-model documentation lists 131,072 maximum output tokens without thinking, or 262,144 tokens for thinking plus the answer. Those are ceilings, not recommended defaults for a first request. Do not copy the preview’s older output figure into released-model configuration.

Connect a direct QwenCloud account

For a pay-as-you-go integration, create or select an API key in the intended QwenCloud region. Follow the official API key instructions and region and endpoint reference. Confirm account access and billing before sending the request.

The example here uses Singapore:

Base URL: https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1
Model: qwen4-max
Protocol: OpenAI-compatible Chat Completions

A Token Plan key uses a separate route. Follow the Token Plan documentation rather than pasting that key into the pay-as-you-go example. The fact that both routes accept a familiar protocol does not merge their entitlements or billing.

Store the key in a server-side environment variable named DASHSCOPE_API_KEY. Avoid committing it or showing it in screenshots. Verify presence without displaying its value:

python3 -c 'import os; print("Key configured:", bool(os.environ.get("DASHSCOPE_API_KEY")))'

This checks only that a value exists. A successful authenticated request establishes whether the selected route accepts it.

Make a small first request and inspect the result

Save this as request.json:

{
  "model": "qwen4-max",
  "messages": [
    {
      "role": "user",
      "content": "Return exactly three short checklist items for reviewing an API integration."
    }
  ],
  "enable_thinking": false,
  "max_completion_tokens": 1024
}

Thinking is explicitly disabled for this narrow connectivity check; it is not a recommendation for every coding or research task. The thinking guide explains the separate controls. A token cap bounds output tokens, not the entire possible cost of a longer tool-using workflow.

Run the following only after selecting the intended billed account:

curl --silent --show-error --fail-with-body \
  --max-time 120 \
  https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  -o response.json

Do not automatically repeat the command after a timeout: the server may have processed a request even if the response did not reach your terminal. First check the provider’s request and usage records. This example deliberately has no automatic retry loop.

Then save the following as check_response.py and run python3 check_response.py response.json:

import json
import sys
from pathlib import Path

payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
if payload.get("error"):
    raise SystemExit("API error: inspect response.json locally.")
choices = payload.get("choices") or []
if not choices:
    raise SystemExit("No choices returned; inspect the response format.")
choice = choices[0]
reason = choice.get("finish_reason")
message = choice.get("message") or {}
text = message.get("content")
if reason != "stop":
    raise SystemExit(f"Incomplete text check: finish_reason={reason!r}")
if not isinstance(text, str) or not text.strip():
    raise SystemExit("No usable final text returned.")
print(text)
print("Usage:", payload.get("usage", "not supplied"))

Passing this check means the response has nonempty text and a normal completion marker. You still need to verify that it contains the three requested items. The script is intentionally specific to a text-only first request: a legitimate tool call is a different intermediate result and should not pass as a finished answer.

For reproducibility, record the request date, endpoint region, returned model identifier, finish reason, usage and task result. Keep raw responses private when they contain user data.

Migrate an existing coding or office agent

Treat migration as two decisions: can the new route execute your protocol, and can the agent still deliver the work? A short greeting answers neither the complete protocol question nor the quality question.

  1. Save the current configuration. Record provider, model, endpoint, client version and tool permissions. Keep a reversible configuration change rather than replacing your working setup everywhere.
  2. Start with an isolated task. Use a small repository or synthetic office documents. Define the expected output before running it: a patch with passing tests, a workbook with reconciled totals, or a report with checkable citations.
  3. Check the client-specific settings. QwenCloud publishes separate guides for Qwen Code, Codex and Claude Code. Configuration for one harness is not a universal API sample.
  4. Run one tool round trip. Ask the agent to inspect a harmless fixture, call a read-only tool, receive its result and use that result in its answer. Check that the tool-call ID and history survive the round trip.
  5. Check an actual deliverable. Open the generated file or review the patch. Verify formulas, citations or tests outside the model’s own statement that it is finished.
  6. Expand gradually. Compare successful task cost, elapsed time and interventions with your current setup on the same inputs. One appealing answer is not enough to replace a production workflow.

A reusable acceptance prompt for a synthetic spreadsheet task:

Use only the supplied sales.csv. Calculate revenue by month from quantity
and unit_price. Flag missing values rather than inventing them. Deliver:
1. the calculation method;
2. the totals with the source row IDs;
3. a list of excluded rows and reasons.
Do not claim to have created an Excel file unless you actually create and
attach one. Stop and report any tool or file-access failure.

This prompt is a proposed test, not a claim that Qwen4 passed it. Recalculate totals independently; then add harder cases such as duplicate rows and currency differences.

Two migration details that can silently break results

Output budgeting changed. The API compatibility notice states that, beginning with the Qwen4 preview generation, max_tokens follows the combined reasoning-and-answer budget semantics. A setting that previously left ample room for visible text may behave differently with reasoning enabled. Inspect completion status and usage before simply raising the cap. Test one change at a time and measure its cost.

Tool history needs more than the visible answer. The function-calling reference and thinking documentation describe how to carry assistant reasoning and tool results across turns. Do not rebuild history from a plain-text transcript and discard protocol fields. For the broader integration pattern, see our multi-turn Qwen and other model tool-call guide; its older model examples are not substitutes for Qwen4’s current contract.

Diagnose the failure before retrying

SymptomFirst checkNext action
Authentication rejectedKey belongs to the selected route and regionCorrect the key/endpoint pairing; do not print secrets into an issue
Model unavailable or not foundExact ID, account entitlement and provider catalogConfirm qwen4-max is offered on that route; do not guess aliases
Request parameter rejectedClient is sending parameters from another model or protocolReduce to the minimal request above, then add required fields one by one
Truncated or empty final answerFinish reason, reasoning budget and output capInspect usage and raw response before changing the budget
Tool loop stallsAssistant tool call, matching result and reasoning historyCompare the serialized messages with the official multi-turn example
Rate limitAccount quota, concurrency and response guidanceReduce concurrency and use bounded backoff where retries are appropriate
Model says “done,” but no file existsTool execution and artifact storageRequire the file and verify its contents before accepting the task

These are diagnostic branches, not claims that we reproduced each error on Qwen4. For distinguishing a wrong identifier from an unsupported endpoint, use our model-not-found troubleshooting guide.

Check cost and Ofox availability separately

QwenCloud’s current pricing reference separates regions and distinguishes input, output and cache operations. Thinking tokens contribute to output billing. A preview credit promotion is not the released model’s universal price, and a Token Plan quota is not a pay-as-you-go unit rate.

For a comparison without caching, calculate input tokens multiplied by the applicable input rate plus output tokens multiplied by the applicable output rate, with both rates normalized to the same token unit. Add every model call in a tool loop. For cached workloads, classify cache writes and reads according to the provider’s billing rules rather than counting those tokens twice. Record the region and pricing date beside the result.

Our November 16 Ofox public catalog snapshot did not list Qwen4-Max. The direct QwenCloud setup above is therefore not an Ofox integration recipe. If you need an existing Ofox route today, inspect the Qwen3.8 Max 0902 model page and assess it as a different model, not an alias for Qwen4.

Ofox users should follow Ofox API key authentication and Ofox error handling for Ofox requests. Those credentials and rules do not authenticate a request to QwenCloud. Confirm a new model’s actual catalog entry and supported protocol before moving the configuration to a gateway.

Frequently Asked Questions

Is Qwen4-Max still preview-only?
No. The current official documentation lists qwen4-max with pay-as-you-go and Token Plan access. qwen4-max-preview is a separate identifier; check its own terms instead of transferring preview conditions to the released model.
Can I call Qwen4-Max through Ofox?
Our November 16, 2026 public catalog check did not find Qwen4-Max. This guide uses QwenCloud directly and does not claim Ofox availability.
Does a one-million-token context mean one million output tokens?
No. The released model documents a 1,000,000-token context, with separate input and output constraints. Its maximum output is 131,072 tokens without thinking, or 262,144 thinking and answer tokens combined.