Como usar a API Qwen 3.8

A Alibaba lançou o Qwen 3.8-Max no início de agosto de 2026, e a API já está disponível no Model Studio. O modelo traz 2,4T de parâmetros totais (95B ativos), janela de contexto de 1M de tokens e preço fixo de US$ 2 para entrada / US$ 6 para saída por milhão de tokens. Para detalhes sobre o modelo, consulte nosso explicador do Qwen 3.8. Este guia foca na implementação: gerar uma chave, escolher uma região, fazer a primeira chamada e integrar o modelo às suas ferramentas.

Experimente o Apidog hoje

O Qwen 3.8 oferece dois protocolos desde o lançamento:

• Um endpoint compatível com OpenAI.
• Um endpoint compatível com Anthropic.

Na prática, seu código com o SDK OpenAI pode continuar funcionando, e sua configuração do Claude Code pode usar o modelo com apenas três variáveis de ambiente. Você também pode testar os dois formatos no Apidog, enviando o mesmo prompt para cada protocolo e comparando as respostas.

O que você precisa antes de começar

Item	Valor
ID do modelo	qwen3.8-max
Janela de contexto	1.000.000 tokens
Saída máxima	65.536 tokens
Tipos de entrada	Texto e imagens
Preços	US$ 2 de entrada / US$ 6 de saída por 1M de tokens, fixo em todo o contexto
Controle de raciocínio	reasoning_effort: xhigh (padrão), medium, low
Protocolos	Chat Completions e Responses compatíveis com OpenAI; Anthropic Messages
Variável de ambiente da chave	DASHSCOPE_API_KEY

Essas informações vêm da postagem oficial de lançamento do Qwen 3.8 e da documentação do Alibaba Cloud Model Studio. A Alibaba prometeu pesos abertos no Hugging Face e no ModelScope para a semana seguinte, mas, no início de agosto de 2026, eles ainda não estavam disponíveis para download. Portanto, todos os exemplos deste guia usam a API hospedada.

Passo 1: obtenha uma chave de API do QwenCloud

Acesse home.qwencloud.com, faça login ou crie uma conta e gere uma chave de API no console.

A plataforma ainda usa o nome DashScope internamente. Por isso, defina a chave na variável DASHSCOPE_API_KEY:

export DASHSCOPE_API_KEY="sk-your-key-here"

Armazene a chave no perfil do shell ou em um arquivo .env. Não a coloque no código-fonte nem a envie para o repositório.

Todos os exemplos abaixo leem essa variável.

Para testar antes de usar créditos pagos, há uma cota gratuita de 1M de tokens válida por 90 dias. Ela está disponível somente na região de Cingapura.

Passo 2: escolha uma URL base regional

O Model Studio disponibiliza a API compatível com OpenAI em três regiões. Escolha a região mais próxima da sua infraestrutura:

Região	URL base
Pequim	https://dashscope.aliyuncs.com/compatible-mode/v1
Cingapura	https://dashscope-intl.aliyuncs.com/compatible-mode/v1
EUA (Virgínia)	https://dashscope-us.aliyuncs.com/compatible-mode/v1

Para a maioria dos usuários internacionais, Cingapura (dashscope-intl) é a escolha padrão. É também a região que oferece a cota gratuita.

A lista de modelos do Model Studio indica que o qwen3.8-max está disponível para geração de texto e compreensão de imagem e vídeo.

Os exemplos deste artigo usam a região de Cingapura. Se necessário, substitua a URL base pela de Pequim ou Virgínia.

Passo 3: faça sua primeira chamada

O endpoint usa o formato Chat Completions da OpenAI. Isso permite usar diretamente o SDK oficial openai para Python, bastando alterar a base_url.

Instale o SDK, se necessário:

pip install openai

Faça uma chamada básica:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "system", "content": "You are a precise technical assistant."},
        {
            "role": "user",
            "content": "Explain idempotency in REST APIs in two sentences.",
        },
    ],
)

print(completion.choices[0].message.content)

A mesma requisição com cURL:

curl https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [
      {
        "role": "user",
        "content": "Explain idempotency in REST APIs in two sentences."
      }
    ]
  }'

Se sua aplicação já usa um provedor compatível com OpenAI, a migração exige basicamente duas mudanças:

1. Atualize a URL base.
2. Troque o ID do modelo para qwen3.8-max.

O fluxo é o mesmo do nosso guia da API Qwen 3.7 Plus.

Passo 4: transmita respostas e leia o raciocínio

O Qwen 3.8-Max é um modelo de raciocínio e raciocina por padrão.

Em streaming, os deltas de reasoning_content chegam antes dos deltas regulares de content. Seu cliente deve tratar os dois campos:

stream = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {
            "role": "user",
            "content": "Design a rate limiting strategy for a public API.",
        }
    ],
    stream=True,
)

thinking_done = False

for chunk in stream:
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)

    if reasoning:
        print(reasoning, end="", flush=True)
    elif delta.content:
        if not thinking_done:
            print("\n--- answer ---")
            thinking_done = True

        print(delta.content, end="", flush=True)

Ao implementar streaming, considere dois pontos:

• Tokens de raciocínio são cobrados como tokens de saída.
• O nível padrão de raciocínio é xhigh, o que pode aumentar latência e custo em interfaces de chat.

Passo 5: ajuste reasoning_effort e os sinalizadores de raciocínio

A API oferece três níveis de reasoning_effort:

Valor	Quando usar
xhigh	Padrão. Indicado para problemas difíceis, código e análise agêntica.
medium	Equilíbrio entre qualidade, custo e latência.
low	Indicado para classificação, extração e chat simples.

Quanto maior o esforço, mais tokens de raciocínio o modelo pode gerar. Isso pode melhorar resultados em tarefas complexas, mas também aumenta custo e latência.

A API também expõe dois sinalizadores:

• enable_thinking: ativa ou desativa o processo de raciocínio.
• preserve_thinking: preserva o contexto de raciocínio entre interações; é ativado por padrão.

No SDK OpenAI, envie esses campos por extra_body, pois são extensões do DashScope:

completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {
            "role": "user",
            "content": "Classify this ticket: 'Login page 500s on Safari.'",
        }
    ],
    extra_body={
        "reasoning_effort": "low",
        "enable_thinking": True,
    },
)

A cobrança é por token, com ou sem raciocínio ativado. O que muda o custo efetivo é a quantidade de tokens de raciocínio gerada pelo modelo, influenciada diretamente por reasoning_effort.

Um padrão prático:

• Use xhigh para codificação e fluxos agênticos.
• Use low em endpoints de alto volume.
• Use medium quando precisar equilibrar qualidade e tempo de resposta.

Sempre avalie esses níveis com prompts e métricas da sua própria carga de trabalho.

O endpoint compatível com Anthropic

Além do endpoint compatível com OpenAI, o Qwen 3.8 oferece um endpoint no protocolo Anthropic Messages:

https://dashscope-intl.aliyuncs.com/apps/anthropic

Esse endpoint permite que ferramentas construídas para a API da Claude se conectem ao Qwen 3.8-Max. O principal caso de uso é o Claude Code.

Configure as variáveis de ambiente:

export ANTHROPIC_BASE_URL=https://dashscope-intl.aliyuncs.com/apps/anthropic
export ANTHROPIC_AUTH_TOKEN=$DASHSCOPE_API_KEY
export ANTHROPIC_MODEL=qwen3.8-max

Depois, inicie o claude. O Claude Code executará seu ciclo agêntico com o Qwen 3.8-Max.

A Alibaba executou a maior parte de seus benchmarks de codificação usando o conjunto de ferramentas do Claude Code. Para mais contexto sobre codificação agêntica, benchmarks e outras integrações documentadas — como Codex, Qoder, Qwen Code e OpenClaw — consulte a análise do Qwen 3.8 para codificação.

O suporte a dois protocolos é útil quando sua equipe mantém ferramentas nos dois ecossistemas. Você pode testar migrações e comparar integrações sem reescrever todos os clientes antes.

Quanto custa

O preço é:

• US$ 2 por milhão de tokens de entrada.
• US$ 6 por milhão de tokens de saída.
• Mesmo preço de 0 a 1M de tokens de contexto.

Não há sobretaxa de contexto longo. O cache de contexto reduz entradas repetidas para 10% do preço de entrada em acertos de cache. A criação explícita de cache é cobrada em 125%.

Consulte a página oficial de preços para os valores atuais.

Em comparação, o preço de lançamento é inferior ao preço de tabela do Qwen 3.7-Max, de US$ 2,5/US$ 7,5.

No entanto, não estime custos apenas pelo preço de entrada e saída do prompt final: tokens de raciocínio também contam como saída, e o nível padrão xhigh pode elevar o consumo total.

Para exemplos detalhados e informações sobre a cota gratuita, consulte a análise completa de preços do Qwen 3.8.

Teste e depure a API Qwen 3.8 no Apidog

Uma API com streaming, raciocínio, três regiões e dois protocolos se beneficia de uma coleção de requisições reproduzível. Você pode configurar isso no Apidog da seguinte forma:

1. Importe a especificação compatível com OpenAI

Crie um projeto e adicione o endpoint de Chat Completions:

POST /chat/completions

Como o formato é compatível com OpenAI, você pode importar uma especificação OpenAI existente e alterar apenas a URL do servidor.

Adicione também o endpoint Anthropic Messages no mesmo projeto. Assim, os dois protocolos ficam disponíveis lado a lado para teste.

2. Modele as regiões como ambientes

Crie três ambientes:

• Pequim
• Cingapura
• EUA-Virgínia

Em cada ambiente, defina:

base_url

Use a URL regional correspondente como valor da variável. Armazene também DASHSCOPE_API_KEY como segredo compartilhado.

Dessa forma, trocar de região exige apenas selecionar outro ambiente, sem editar cada requisição manualmente. Isso também facilita comparar a latência entre regiões antes de escolher uma para produção.

3. Inspecione o fluxo SSE

Envie uma requisição com streaming ativado:

{
  "stream": true
}

Na resposta, observe os eventos enviados pelo servidor. Primeiro devem chegar deltas de reasoning_content; depois, deltas de content.

Essa inspeção é útil para depurar parsers de streaming. Compare os eventos SSE brutos com o que sua aplicação processa para identificar se o problema está no cliente ou no provedor.

4. Compare modelos lado a lado

Duplique uma requisição e altere o modelo para:

qwen3.7-max

Execute as duas requisições com o mesmo prompt e registre:

• Tempo de resposta.
• Contagem de tokens.
• Qualidade da resposta.
• Comportamento do streaming.

Você também pode manter uma requisição da API Kimi K3 no mesmo projeto para testes A/B com a sua carga de trabalho real.

Benchmarks de fornecedores são úteis como ponto de partida, mas seus próprios prompts e métricas devem orientar a decisão.

Baixe o Apidog gratuitamente para criar esse ambiente de teste.

Perguntas frequentes

Existe uma maneira gratuita de experimentar a API Qwen 3.8?

Sim. Novas contas do Model Studio recebem uma cota gratuita de 1M de tokens para qwen3.8-max, válida por 90 dias e disponível apenas na região de Cingapura.

Para usar essa cota, direcione o tráfego de avaliação para:

https://dashscope-intl.aliyuncs.com/compatible-mode/v1

Posso executar o Qwen 3.8 localmente em vez de usar a API?

Ainda não. A Alibaba prometeu pesos abertos no Hugging Face e ModelScope para a semana seguinte, mas eles ainda não estavam disponíveis para download no início de agosto de 2026.

Com 2,4T de parâmetros totais, a auto-hospedagem também exigirá um ambiente de vários nós, mesmo com quantização. Por enquanto, a API hospedada é a única forma de executar o modelo.

O endpoint Anthropic suporta os mesmos recursos que o OpenAI?

O endpoint Anthropic usa o protocolo Anthropic Messages e existe principalmente para ferramentas desse ecossistema, com Claude Code como integração oficialmente documentada.

Para integração direta em aplicações, o endpoint compatível com OpenAI é o caminho mais documentado. Ele cobre reasoning_effort, enable_thinking e streaming com reasoning_content.

Como o qwen3.8-max se compara ao Qwen3-Coder para codificação?

São ferramentas diferentes.

O Qwen3-Coder é uma linha de modelos especializada em programação. Já o qwen3.8-max é o modelo geral de ponta, com números fortes em codificação agêntica na tabela da Alibaba, incluindo 86,6 no Terminal Bench 2.1 segundo benchmarks executados pelo fornecedor.

Se estiver escolhendo entre os dois, teste ambos com os mesmos prompts. As chamadas de API são idênticas, exceto pelo ID do modelo.

Conclusão

A API Qwen 3.8 é simples de adotar em projetos existentes:

• Código com SDK OpenAI funciona após atualizar a URL base.
• Claude Code funciona após configurar três variáveis de ambiente.
• O preço fixo de US$ 2/US$ 6 simplifica a previsão de custos em até 1M de tokens de contexto.

Ao colocar em produção, acompanhe especialmente:

• Tokens de raciocínio, cobrados como saída.
• O uso padrão de reasoning_effort: xhigh.
• A disponibilidade regional da cota gratuita.

Comece pela cota gratuita de Cingapura. Faça chamadas com streaming, valide como sua aplicação processa os deltas de raciocínio e compare os resultados com seus próprios prompts antes de confiar apenas em benchmarks.

Por fim, organize as requisições no Apidog: configure regiões como ambientes e salve ambos os protocolos no mesmo projeto. Isso torna a avaliação reproduzível para toda a equipe quando o próximo modelo for lançado.