API do Qwen4-Max: Guia Completo com Exemplos de Código
A API do Qwen4-Max já está disponível no QwenCloud como um modelo pay-per-token com o ID qwen4-max. Crie uma chave pré-paga na sua região, aponte o SDK da OpenAI para https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1 (Singapura) e faça a chamada. Custa US$ 1,50 por milhão de tokens de entrada e US$ 4,50 por milhão de tokens de saída, com um contexto de 1 milhão de tokens.
Este guia aborda a chave, URLs base, thinking, visão, tools, saídas estruturadas, cache, a rota Anthropic, limites e erros. Todos os trechos de código seguem a documentação do QwenCloud conforme lida em 16 de novembro de 2026.
Para conhecer o contexto, leia o que é o Qwen4-Max. Para acesso por assinatura em vez de pagamento por token, veja todas as formas de usar o Qwen4-Max e o guia do Token Plan.
O que a API do Qwen4-Max oferece
A API do Qwen4-Max é o modelo flagship da Alibaba servido via QwenCloud, com endpoints compatíveis com OpenAI, Anthropic e DashScope. Ela aceita entrada de texto, imagem e vídeo, retorna texto, pensa antes de responder por padrão e suporta function calling, saídas estruturadas, cache de contexto, jobs em lote, busca na web e fine-tuning.
Veja os números da página do modelo qwen4-max:
| Item | Valor |
|---|---|
| ID do modelo | qwen4-max |
| Preço de entrada | US$ 1,50 por 1 milhão de tokens |
| Preço de saída | US$ 4,50 por 1 milhão de tokens |
| Cache implícito de entrada / leitura de cache explícito | US$ 0,075 por 1 milhão de tokens |
| Criação de cache explícito | US$ 1,875 (5 minutos) ou US$ 3 (1 hora) por 1 milhão de tokens |
| Janela de contexto | 1 milhão de tokens |
| Entrada máxima | 991 mil (983 mil com thinking) |
| Saída máxima | 393 mil |
| Raciocínio máximo | 262 mil |
| Vazão | 5.000.000 TPM |
Tokens de thinking são cobrados como tokens de saída. Para uma análise completa de custos, veja o guia de preços do Qwen4-Max.
Obtenha uma chave e escolha a URL base correta
As chaves estão vinculadas a uma região, e o tipo de chave precisa corresponder ao endpoint.
- Abra o console do QwenCloud e escolha uma região no seletor no canto superior direito.
- Vá para API Keys, clique em Create API key, adicione uma descrição e clique em Generate Key.
- Copie a chave imediatamente. Ela é exibida apenas uma vez. As novas chaves pré-pagas começam com
sk-ws-. - Exporte a chave:
export DASHSCOPE_API_KEY="sk-ws-...".
Cada região usa o domínio {region}.maas.qwencloudapi.com. Singapura é ap-southeast-1; Frankfurt é eu-central-1, Tóquio é ap-northeast-1 e EUA (Virgínia) é us-east-1. Em seguida, acrescente o caminho do protocolo:
| Protocolo | URL base (Singapura) |
|---|---|
| Compatível com OpenAI (Chat Completions, Responses) | https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1 |
| Compatível com Anthropic | https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic |
| DashScope HTTP | https://ap-southeast-1.maas.qwencloudapi.com/api/v1 |
Uma chave do Token Plan (sk-sp-) só funciona em token-plan.maas.qwencloudapi.com, e uma chave pré-paga só funciona no domínio da sua própria região. Misturá-las gera um erro 401. Veja regiões e endpoints.
Sua primeira chamada à API do Qwen4-Max
Instale o SDK da OpenAI (pip install openai) e execute o quickstart da documentação:
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)
O thinking está ativado por padrão no qwen4-max, então essa chamada também consome tokens de raciocínio. Para prompts longos, use streaming ou configure um timeout de cliente de 180 segundos ou mais.
Modo thinking e streaming de reasoning_content
O Qwen4-Max é um modelo híbrido com thinking. Os padrões documentados são enable_thinking=true, reasoning_effort=high e thinking_budget=131072. Os níveis de esforço são low, high e xhigh; none desativa o thinking.
Faça o streaming do raciocínio e da resposta em duas fases (adaptado do exemplo da página do modelo):
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
Três regras:
-
Limite a saída com
max_completion_tokens. Com o thinking ativado,max_tokenssó aceita valores de 1 a 32.768 (caso contrário, retorna 400). Omax_completion_tokenscobre raciocínio mais resposta sem esse limite. -
Ajuste a profundidade com
extra_body. Passe{"enable_thinking": True, "reasoning_effort": "xhigh"}para problemas difíceis, ou"low"para os simples. -
Preserve o raciocínio em conversas multi-turno. O
qwen4-maxtempreserve_thinkingativado por padrão, então envie o raciocínio anterior de volta no camporeasoning_contentde cada mensagem do assistente, nunca dentro decontent.
Para pular o thinking, passe {"enable_thinking": False}.
Entrada de imagem e vídeo
Envie imagens como partes image_url e vídeos como partes video_url. Isso espelha o exemplo de visão da documentação com o modelo definido como 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"},
],
}],
)
Para vídeo, use {"type": "video_url", "video_url": {"url": "..."}, "fps": 2}. Arquivos locais são enviados como Data URIs em Base64.
O guia de visão permite até 2.048 imagens por URL de 20 MB cada, 250 imagens em Base64 e 64 MB por requisição. O detalhamento de imagem é definido como high por padrão, o que custa mais tokens de entrada.
Function calling
Passe um array tools como em qualquer modelo compatível com OpenAI:
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)
Leia message.tool_calls, execute a função, acrescente uma mensagem tool e faça a chamada novamente.
No modo thinking, tool_choice só aceita "auto" ou "none"; para forçar uma função, desative o thinking primeiro. Com o thinking ativado, envie reasoning_content de volta junto com os resultados das ferramentas, ou a precisão cai.
Saídas estruturadas
O qwen4-max suporta o modo estrito de JSON Schema:
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,
},
},
},
)
Com o modo mais flexível {"type": "json_object"}, a palavra "JSON" precisa aparecer em alguma mensagem, ou a API rejeita a requisição. Entrada de imagem ou vídeo recorre a json_object, então o schema não é aplicado em chamadas multimodais.
Cache de contexto e batch
Cache. Sem configurações, o cache implícito corresponde prefixos, mas não garante acertos. Para acertos determinísticos, use o cache explícito do Qwen4: marque um bloco de conteúdo com "prompt_cache_breakpoint": {"mode": "explicit"} (o content da mensagem precisa ser um array) e defina o TTL com extra_body={"prompt_cache_options": {"mode": "explicit", "ttl": "5m"}}. O TTL é 5m ou 1h, e o prefixo em cache precisa ter pelo menos 1.024 tokens. Leituras custam US$ 0,075 por milhão de tokens, 95% menos do que entrada nova.
Batch. O guia de batch cobra entrada e saída a 50% do preço em tempo real e retorna resultados em até 24 horas. Para o qwen4-max, o Batch File roda em uma região fora de Singapura e não suporta cache de contexto, então consulte o guia de batch antes de planejar um pipeline em torno dele.
A rota compatível com Anthropic
Já usa o SDK da Anthropic? Basta trocar a URL base e a chave:
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)
Este exemplo desativa o thinking, assim como o exemplo da própria documentação. Termine a URL base em /apps/anthropic. Adicionar /v1/ produz /v1/v1/... e um erro 404. O thinking também está ativado por padrão aqui, e com o thinking habilitado o max_tokens precisa exceder o orçamento de thinking. O esforço usa output_config.effort (low, high, xhigh), e as ferramentas integradas web_search e web_fetch estão disponíveis nesta rota.
Limites de taxa da API do Qwen4-Max
| Região | RPM | TPM |
|---|---|---|
| Singapura | Dinâmico | Camadas dinâmicas: 5M, 10M, 20M |
| Frankfurt, Tóquio, EUA (Virgínia) e outras regiões de escopo global | 30.000 | 5.000.000 |
Os limites se aplicam por conta por região e também por segundo (RPS = RPM / 60), então um pico pode fazer você atingir o limite antes do total por minuto.
A página de cota gratuita informa que a cota gratuita existe apenas em Singapura, é por modelo (normalmente 1.000.000 tokens), dura 90 dias e exige dados de pagamento cadastrados. Ela não menciona o qwen4-max, então verifique a página do Free Tier no console, ou leia como usar o Qwen4-Max de graça.
Erros comuns da API do Qwen4-Max
| Código | Significado | Solução |
|---|---|---|
401 InvalidApiKey
|
A chave e a URL base são de regiões diferentes, ou uma chave do Token Plan foi usada em um endpoint pré-pago | Use uma chave criada na mesma região da URL |
400 InvalidParameter
|
Frequentemente, max_tokens fora do intervalo de 1 a 32.768 com o thinking ativado |
Mude para max_completion_tokens
|
403 AllocationQuota.FreeTierOnly
|
Cota gratuita esgotada antes da configuração de pagamento | Adicione os dados de pagamento na página do Free Tier |
404 ModelNotFound
|
O qwen4-max não é oferecido na região chamada |
Verifique os preços do modelo para essa região |
429 Throttling
|
Limite de RPM ou TPM atingido | Aguarde e tente novamente, ou distribua a carga ao longo dos segundos |
Deixe seu agente de código testar a API do Qwen4-Max com o Apidog CLI
Seu agente de código escreve a integração, então deixe que ele escreva também o teste de regressão. O Apidog CLI permite que ele salve o endpoint, armazene a chave e execute asserções.
Configure uma vez:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
Depois, dê um único prompt ao seu agente:
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.
O agente lê o schema de cada payload antes de escrever, e então executa o caso de teste:
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
O reportador cli imprime aprovação ou falha; o json gera um relatório que o agente lê. Mova o mesmo apidog run ... -r junit para o CI com o guia de CI/CD do Apidog CLI e veja Apidog CLI no Claude Code para mais prompts. O plano gratuito do Apidog cobre até 4 usuários.
Perguntas frequentes
Qual é o ID do modelo da API do Qwen4-Max?
O ID estável é qwen4-max. O ID anterior qwen4-max-preview era exclusivo do Token Plan durante a prévia iniciada em 11 de novembro de 2026.
A API do Qwen4-Max é compatível com OpenAI?
Sim. Use o SDK da OpenAI com a URL base /compatible-mode/v1 para Chat Completions e a API Responses. Um endpoint compatível com Anthropic e a API DashScope também estão disponíveis.
Como desativar o thinking na API do Qwen4-Max?
Passe extra_body={"enable_thinking": False}. Você perde o reasoning_content, mas a latência e os tokens de saída diminuem. Comparando modelos? Veja Qwen4-Max vs Qwen3.8.
Quanto custa a API do Qwen4-Max?
US$ 1,50 por milhão de tokens de entrada e US$ 4,50 por milhão de tokens de saída, com leituras em cache a US$ 0,075 por milhão.
Posso usar minha chave do Token Plan com a API pré-paga?
Não. As chaves do Token Plan (sk-sp-) só funcionam em token-plan.maas.qwencloudapi.com, e as chaves pré-pagas só funcionam no domínio da sua própria região.



Top comments (0)