Como usar a API do Qwen4-Max e migrar da versão preview
Configure o ID, a região e a cobrança corretos do Qwen4-Max. Confira a primeira resposta, os limites de saída e o histórico de ferramentas antes de migrar seu agente.
O Qwen4-Max agora está documentado como modelo lançado, com o identificador de API qwen4-max. Ele é diferente de qwen4-max-preview. Se um artigo antigo disser que o Qwen4 só está disponível em uma assinatura de preview, consulte a documentação oficial atual antes de configurar a aplicação.
Este guia foi verificado em 16 de novembro de 2026. Ele usa a API direta da QwenCloud, explica as decisões de migração e fornece um pequeno validador de respostas. Conferimos a documentação e casos sintéticos locais; não fizemos chamadas pagas ao Qwen4 nem benchmarks do modelo para este artigo. Os exemplos são requisições para executar e critérios de aceitação, não resultados de desempenho medidos.
O que mudou e qual modelo selecionar?
A página oficial do modelo passou a descrever qwen4-max, enquanto materiais de preview usam outro identificador. Utilize o nome exato disponível na rota escolhida. Não acrescente um prefixo de outro gateway nem presuma que o nome exibido no cliente seja o ID da API.
O modelo lançado documenta geração de texto, compreensão de imagens e vídeos, chamadas de ferramentas e saída estruturada. Em tarefas de escritório, uma distinção importa: compreender uma imagem não equivale a gerar uma imagem; devolver conteúdo de slides não cria, por si só, uma apresentação editável. Criar arquivos, executar ações e entregar resultados exige ferramentas adequadas e um ambiente de agente que confira seus resultados.
| Decisão | O que conferir antes de mudar a configuração |
|---|---|
| Modelo lançado ou preview | Use qwen4-max neste guia; mantenha a configuração de preview separada |
| API direta ou gateway | Verifique catálogo, credenciais e protocolos daquele provedor |
| Pagamento por uso ou Token Plan | Use o endpoint e a chave correspondentes à modalidade |
| Região | Alinhe região do console, chave e endpoint |
| Migração do agente | Valide a tarefa concluída e seus arquivos, não apenas um HTTP bem-sucedido |
O limite oficial de contexto é de 1.000.000 de tokens. A documentação do modelo lançado informa 131.072 tokens máximos de saída sem thinking, ou 262.144 tokens de thinking e resposta somados. São tetos, não valores iniciais recomendados. Não copie o limite antigo do preview para a configuração do modelo lançado.
Conecte uma conta direta da QwenCloud
Para pagar por uso, crie ou selecione uma chave na região desejada da QwenCloud. Siga as instruções oficiais de chave de API e a referência de regiões e endpoints. Confirme o acesso e a cobrança antes de enviar a requisição.
Este exemplo usa Singapura:
Base URL: https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1
Model: qwen4-max
Protocol: OpenAI-compatible Chat Completions
A chave do Token Plan usa uma rota separada. Siga a documentação do Token Plan, em vez de colocar essa chave no exemplo de pagamento por uso. Aceitar um protocolo semelhante não une permissões de acesso ou faturamento.
Guarde a chave no servidor, na variável DASHSCOPE_API_KEY. Não a coloque no repositório nem em capturas de tela. Confira sua presença sem mostrar o valor:
python3 -c 'import os; print("Key configured:", bool(os.environ.get("DASHSCOPE_API_KEY")))'
Isso verifica apenas se existe um valor. Uma requisição autenticada bem-sucedida confirma se a rota escolhida o aceita.
Faça uma primeira chamada pequena e inspecione a resposta
Salve como 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
}
O thinking está explicitamente desativado neste teste restrito de conexão. Isso não é uma recomendação geral para programação ou pesquisa. O guia de thinking explica os controles separados. Um teto de tokens limita a saída, não todo o custo possível de um fluxo longo com ferramentas.
Execute somente depois de selecionar a conta que deve ser cobrada:
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
Não repita o comando automaticamente após um timeout: o servidor pode ter processado a chamada mesmo que a resposta não tenha chegado ao terminal. Consulte primeiro os registros de requisições e uso do provedor. O exemplo não inclui repetição automática de propósito.
Salve o código abaixo como check_response.py e execute 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"))
Passar nessa verificação significa receber texto não vazio e uma indicação normal de término. Ainda é necessário conferir se a resposta contém os três itens pedidos. O script foi feito especificamente para a primeira chamada somente de texto. Uma chamada legítima de ferramenta é outro resultado intermediário e não deve passar como resposta final.
Para reproduzir o teste, registre data, região do endpoint, identificador retornado, motivo de término, uso e resultado da tarefa. Mantenha privadas as respostas brutas que contenham dados de usuários.
Migre um agente de programação ou de escritório
Separe duas decisões: a nova rota executa o seu protocolo? E o agente continua entregando o trabalho? Uma saudação curta não responde integralmente à questão do protocolo nem à da qualidade.
- Salve a configuração atual. Registre provedor, modelo, endpoint, versão do cliente e permissões de ferramentas. Faça uma mudança reversível em vez de substituir a configuração funcional em todos os ambientes.
- Comece com uma tarefa isolada. Use um repositório pequeno ou documentos sintéticos. Defina a entrega antes da execução: patch com testes passando, planilha com totais conferidos ou relatório com citações verificáveis.
- Confira os ajustes específicos do cliente. A QwenCloud publica guias separados para Qwen Code, Codex e Claude Code. Uma configuração de ambiente não é um exemplo universal de API.
- Execute um ciclo completo de ferramenta. Peça que o agente examine um arquivo de teste inofensivo, chame uma ferramenta somente leitura, receba o resultado e o use na resposta. Confira se o ID da chamada e o histórico são preservados.
- Confira a entrega real. Abra o arquivo ou revise o patch. Verifique fórmulas, citações ou testes independentemente da afirmação do modelo de que terminou.
- Amplie aos poucos. Compare custo de tarefas concluídas, duração e intervenções com a configuração atual usando as mesmas entradas. Uma resposta convincente não basta para substituir um fluxo de produção.
Prompt reutilizável de aceitação para uma tarefa sintética com planilha:
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.
Esse prompt propõe um teste; não afirma que o Qwen4 passou nele. Recalcule os totais por conta própria e depois inclua casos mais difíceis, como linhas duplicadas e moedas diferentes.
Dois detalhes da migração que podem prejudicar o resultado sem aviso
O orçamento de saída mudou. O aviso de compatibilidade da API informa que, a partir da geração preview do Qwen4, max_tokens segue a semântica de orçamento conjunto para raciocínio e resposta. Um valor antes suficiente para texto visível pode se comportar de outra forma com thinking ativo. Inspecione o status de término e o uso antes de aumentar o limite. Altere uma configuração por vez e meça o custo.
O histórico precisa de mais que a resposta visível. A referência de chamadas de funções e a documentação de thinking explicam como preservar o raciocínio do assistente e os resultados das ferramentas entre turnos. Não reconstrua o histórico a partir de uma transcrição simples descartando campos do protocolo. Veja o padrão geral no nosso guia de ferramentas em vários turnos com Qwen e outros modelos (em inglês); os exemplos de modelos anteriores não substituem o contrato atual do Qwen4.
Diagnostique antes de tentar novamente
| Sintoma | Primeira verificação | Próxima ação |
|---|---|---|
| Autenticação rejeitada | Chave pertence à rota e região selecionadas | Corrija a combinação; não publique segredos ao relatar o erro |
| Modelo indisponível ou não encontrado | ID exato, permissão da conta e catálogo | Confirme que a rota oferece qwen4-max; não presuma aliases |
| Parâmetro rejeitado | Cliente envia parâmetros de outro modelo ou protocolo | Reduza à chamada mínima e acrescente os campos necessários um por vez |
| Resposta final truncada ou vazia | Motivo de término, orçamento de raciocínio e limite de saída | Inspecione uso e resposta bruta antes de alterar o orçamento |
| Ciclo de ferramentas parado | Chamada do assistente, resultado correspondente e histórico de raciocínio | Compare as mensagens serializadas com o exemplo oficial de vários turnos |
| Limite de requisições | Cota, concorrência e orientações da resposta | Reduza a concorrência e use tentativas limitadas com espera quando forem apropriadas |
| Modelo diz “pronto”, mas não há arquivo | Execução da ferramenta e armazenamento | Exija o arquivo e verifique o conteúdo antes de aceitar a tarefa |
Esses são caminhos de diagnóstico, não afirmações de que reproduzimos todos os erros no Qwen4. Para diferenciar um ID incorreto de um endpoint incompatível, veja nosso guia de “model not found” (em inglês).
Confira custos e disponibilidade na Ofox separadamente
A referência atual de preços da QwenCloud separa regiões e distingue entrada, saída e operações de cache. Tokens de thinking entram na cobrança de saída. Uma promoção de créditos do preview não é o preço universal do modelo lançado; uma cota do Token Plan não equivale à tarifa por uso.
Sem cache, calcule tokens de entrada vezes a tarifa correspondente, mais tokens de saída vezes sua tarifa, normalizando ambos para a mesma unidade. Some todas as chamadas do ciclo de ferramentas. Com cache, classifique escritas e leituras pelas regras de cobrança do provedor, sem contar tokens duas vezes. Registre região e data dos preços junto do cálculo.
Nosso snapshot de 16 de novembro do catálogo público da Ofox não listava Qwen4-Max. Portanto, a configuração direta da QwenCloud acima não é uma receita de integração pela Ofox. Se precisa de uma rota já disponível na Ofox, consulte a página do Qwen3.8 Max 0902 e avalie-o como outro modelo, não como um alias do Qwen4.
Para chamadas à Ofox, siga a autenticação por chave da Ofox e o tratamento de erros da Ofox. Essas credenciais e regras não autenticam chamadas à QwenCloud. Confirme o catálogo e o protocolo efetivamente suportado antes de mover a configuração de um novo modelo para um gateway.
Perguntas frequentes
- O Qwen4-Max ainda está restrito à versão preview?
- Não. A documentação oficial atual lista qwen4-max com acesso por uso e pelo Token Plan. qwen4-max-preview é um identificador separado; confira suas próprias condições, sem transferi-las para o modelo lançado.
- Posso chamar o Qwen4-Max pela Ofox?
- Nossa consulta ao catálogo público em 16 de novembro de 2026 não encontrou Qwen4-Max. Este guia usa QwenCloud diretamente e não afirma que o modelo esteja disponível na Ofox.
- Um milhão de tokens de contexto significa um milhão de tokens de saída?
- Não. O modelo lançado documenta contexto de 1.000.000 de tokens, com limites separados de entrada e saída. A saída máxima é de 131.072 tokens sem thinking ou 262.144 tokens de thinking e resposta somados.


