DEV Community

Cover image for Como usar a API do Qwen4-Max
Lucas
Lucas

Posted on Originally published at apidog.com

Como usar a API do Qwen4-Max

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.

Experimente o Apidog hoje

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.

Imagem do modelo

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.

  1. Abra o console do QwenCloud e escolha uma região no seletor no canto superior direito.
  2. Vá para API Keys, clique em Create API key, adicione uma descrição e clique em Generate Key.
  3. Copie a chave imediatamente. Ela é exibida apenas uma vez. As novas chaves pré-pagas começam com sk-ws-.
  4. 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

Diagrama de uma única chave pré-paga qwen4-max alcançando o domínio de Singapura, que atende a três caminhos: /compatible-mode/v1 para o SDK da OpenAI, /apps/anthropic para o SDK da Anthropic e /api/v1 para o DashScope

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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Três regras:

  • Limite a saída com max_completion_tokens. Com o thinking ativado, max_tokens só aceita valores de 1 a 32.768 (caso contrário, retorna 400). O max_completion_tokens cobre 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-max tem preserve_thinking ativado por padrão, então envie o raciocínio anterior de volta no campo reasoning_content de cada mensagem do assistente, nunca dentro de content.

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"},
    ],
  }],
)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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,
      },
    },
  },
)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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

Da página de limites de taxa:

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.

Fluxo de um único prompt para um agente de código, que executa apidog environment create, endpoint create, test-case create com asserções de status, choices, usage e reasoning_content, e depois apidog run para um relatório de aprovação ou falha

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
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)