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 um total de 2.4T parâmetros (95B ativos), uma janela de contexto de 1M de tokens, e um preço fixo de $2 de entrada / $6 de saída por milhão de tokens. Se você quiser saber tudo sobre o modelo em si, comece com nosso explicador do Qwen 3.8. Este guia aborda o lado prático: como obter uma chave, escolher uma região, fazer sua primeira chamada e integrar o modelo às suas ferramentas.

Um detalhe diferencia esta API da maioria dos lançamentos de modelos. O Qwen 3.8 é lançado com dois protocolos desde o primeiro dia: um endpoint compatível com OpenAI e um endpoint compatível com Anthropic. Seu código SDK OpenAI existente funciona. Sua configuração do Claude Code também funciona, com três variáveis de ambiente. Esse design de protocolo duplo também torna esta API divertida de explorar no Apidog, onde você pode enviar o mesmo prompt para ambos os formatos de protocolo e observar como cada um retorna os dados. Mais sobre isso abaixo.

Aqui está o guia completo.

O que você precisa antes de começar

Uma referência rápida para que nada abaixo o surpreenda:

Tudo isso vem da postagem de lançamento oficial do Qwen 3.8 e da documentação do Alibaba Cloud Model Studio. Uma observação sobre os pesos: a Alibaba prometeu pesos abertos no Hugging Face e ModelScope para a próxima semana, mas no início de agosto de 2026 eles ainda não estão disponíveis para download. Tudo neste guia é executado na API hospedada.

Passo 1: obtenha uma chave de API do QwenCloud

Vá para home.qwencloud.com e faça login ou crie uma conta. Assim que estiver no console, crie uma chave de API. A plataforma da Alibaba ainda usa o nome DashScope internamente, então a convenção da variável de ambiente é DASHSCOPE_API_KEY:

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

Coloque-o no seu perfil de shell ou em um arquivo .env, não no seu código-fonte. Cada trecho neste guia lê a chave dessa variável.

Se você quiser testar o modelo antes de gastar dinheiro de verdade, há uma cota gratuita: 1M de tokens, válida por 90 dias, disponível apenas na região de Cingapura. Isso é o suficiente para uma avaliação séria.

Passo 2: escolha uma URL base regional

O Model Studio serve a API compatível com OpenAI a partir de três regiões. Escolha a mais próxima dos seus servidores:

O endpoint de Cingapura (dashscope-intl) é a escolha padrão para a maioria dos usuários internacionais, e é onde a cota gratuita está disponível. A lista de modelos do Model Studio confirma que o qwen3.8-max está disponível para geração de texto, além de compreensão de imagem e vídeo, e está no topo da tabela de modelos recomendados a partir da atualização de 3 de agosto.

Os exemplos abaixo usam Cingapura. Troque a URL base se você estiver mais perto de Pequim ou Virgínia.

Passo 3: faça sua primeira chamada

O endpoint fala o formato de conclusões de chat OpenAI, então o SDK oficial do Python openai funciona como está. Aponte-o para a URL base do DashScope:

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 chamada em 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 você já usou qualquer provedor compatível com OpenAI antes, nada aqui parecerá novo. Esse é o objetivo. A migração de outro modelo é uma troca de URL base e uma alteração de ID do modelo. Se você vem da geração anterior, o fluxo de trabalho é idêntico ao do nosso guia da API Qwen 3.7 Plus, apenas com um novo ID de modelo e números melhores por trás dele.

Passo 4: transmita respostas e leia o raciocínio

Qwen 3.8-Max é um modelo de raciocínio, e ele pensa por padrão. No modo de streaming, o raciocínio chega como deltas de reasoning_content antes que a resposta final chegue como deltas regulares de content. Lide com ambos:

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)

Duas coisas a saber sobre o fluxo de raciocínio. Primeiro, os tokens de raciocínio são cobrados como tokens de saída na mesma taxa que todo o resto, então longas cadeias de raciocínio aparecerão em sua fatura. Segundo, no nível de esforço padrão, o modelo raciocina intensamente, o que é ótimo para a correção e lento para UIs de chat. Isso nos leva aos controles.

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

A API expõe três níveis oficiais de reasoning_effort: xhigh (o padrão), medium (médio) e low (baixo). Um esforço maior significa mais tokens de raciocínio, melhores resultados em problemas difíceis e maior latência, além de custo. Um esforço menor é a escolha certa para classificação, extração e chat simples.

Dois sinalizadores relacionados controlam o próprio comportamento de raciocínio: enable_thinking liga ou desliga o processo de raciocínio, e preserve_thinking (ativado por padrão) mantém o contexto de raciocínio entre as interações. Passe-os através de extra_body quando estiver usando o SDK OpenAI, 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 é idêntica, esteja o raciocínio ativado ou desativado, por token. A alavanca que altera seus custos é a quantidade de tokens de raciocínio que o modelo gera, que reasoning_effort controla diretamente. Um padrão sensato: xhigh para codificação e análise agêntica, low para endpoints de produção de alto volume, medium quando você não tiver certeza. Avalie sua própria carga de trabalho em vez de confiar nos padrões de qualquer um, incluindo os da Alibaba.

O endpoint compatível com Anthropic

Esta é a parte incomum. Junto com a API compatível com OpenAI, o Qwen 3.8 oferece um endpoint de protocolo Anthropic:

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

Ele fala o formato Anthropic Messages, o que significa que qualquer ferramenta construída para a API de Claude pode se comunicar com o Qwen 3.8-Max sem alterações de código. O principal caso de uso é o Claude Code. A Alibaba publicou uma configuração oficial, e são três 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

Inicie claude depois de configurá-los, e o Claude Code executa seu ciclo agêntico completo com o Qwen 3.8-Max. Há um detalhe que vale a pena ressaltar aqui: a Alibaba executou a maioria de seus próprios benchmarks de codificação com o conjunto de ferramentas do Claude Code. O endpoint Anthropic não é uma reflexão tardia de compatibilidade; é a configuração que o próprio fornecedor usou para produzir os números de codificação. Se a codificação agêntica é o seu caso de uso, nossa análise do Qwen 3.8 para codificação detalha essas linhas de benchmark e os outros conjuntos de ferramentas suportados (Codex, Qoder, Qwen Code e OpenClaw também têm configurações oficiais).

Por que o protocolo duplo importa além do Claude Code? Porque sua equipe provavelmente tem código e ferramentas divididas entre os dois ecossistemas. Uma API que responde a ambos os formatos significa que você pode testar uma migração em qualquer direção sem reescrever os clientes primeiro.

Quanto custa

Versão resumida: $2 por milhão de tokens de entrada, $6 por milhão de tokens de saída, um nível fixo de 0 a 1M de contexto. Sem sobretaxa de contexto longo, o que é raro entre modelos de contexto de 1M. O cache de contexto reduz a entrada repetida para 10% do preço de entrada em acertos de cache, com a criação explícita de cache cobrada em 125%. A página oficial de preços tem os números atuais.

Para comparação, esse preço de lançamento é inferior ao preço de tabela do Qwen 3.7-Max de $2.5/$7.5. Lembre-se, porém, da nota de cobrança da seção de streaming: os tokens de raciocínio contam como saída, e o nível de esforço padrão é xhigh, então as contas reais são mais altas do que um cálculo ingênuo de preço de etiqueta. Para exemplos de custos detalhados e as letras miúdas da cota gratuita, veja a análise completa de preços do Qwen 3.8.

Teste e depure a API Qwen 3.8 no Apidog

Uma API de raciocínio por streaming, de protocolo duplo e três regiões, é exatamente o tipo de superfície onde um ambiente de trabalho de API adequado vale a pena. Aqui está uma configuração prática no Apidog:

Importe a especificação compatível com OpenAI. Crie um projeto e adicione o endpoint de conclusões de chat (POST /chat/completions) com o esquema do corpo da requisição. Como a API segue o formato OpenAI, você pode importar uma especificação OpenAI existente e alterar apenas a URL do servidor. Adicione o endpoint Anthropic Messages como uma segunda API no mesmo projeto para que ambos os formatos de protocolo coexistam lado a lado.

Modele as regiões como ambientes. Crie três ambientes Apidog (Pequim, Cingapura, EUA-Virgínia), cada um com uma variável base_url definida para a URL compatível correspondente e um segredo DASHSCOPE_API_KEY compartilhado. Alternar entre regiões se torna um clique no menu suspenso em vez de uma edição em cada requisição. Esta é também a maneira limpa de verificar a latência de sua localização em relação a cada região antes de confirmar uma para produção.

Inspecione o fluxo SSE. Envie uma requisição com "stream": true e observe os eventos brutos enviados pelo servidor na visualização da resposta. Você verá os deltas de reasoning_content chegarem primeiro, e depois os deltas de content. Quando seu analisador de streaming se comporta mal em produção, comparar sua saída com a sequência de eventos brutos no Apidog é a maneira mais rápida de descobrir se o bug é seu ou do provedor.

Compare modelos lado a lado. Duplique uma requisição, altere o ID do modelo para qwen3.7-max e execute ambos com o mesmo prompt. O mesmo truque funciona entre provedores: mantenha uma requisição da API Kimi K3 no mesmo projeto e faça um teste A/B dos dois modelos de código aberto de ponta em sua carga de trabalho real, com tempos de resposta e contagens de tokens registrados para cada execução. As tabelas de benchmark do fornecedor são um ponto de partida; seus próprios prompts são o teste real.

Baixe o Apidog gratuitamente para acompanhar; toda a configuração acima leva cerca de dez minutos.

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, apenas na região de Cingapura. Essa é a oferta completa, então direcione seu tráfego de avaliação através de dashscope-intl para usá-la.

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 próxima semana, mas no início de agosto de 2026 eles ainda não estão disponíveis para download. E com 2.4T parâmetros totais, a auto-hospedagem será um projeto de vários nós, mesmo quantizado. Por enquanto, a API hospedada é a única maneira de executar o modelo.

O endpoint Anthropic suporta os mesmos recursos que o OpenAI? O endpoint Anthropic fala o protocolo Anthropic Messages e existe principalmente para alimentar ferramentas desse ecossistema, com o Claude Code como a integração oficialmente documentada. Para código de aplicação direta, o endpoint compatível com OpenAI é o caminho mais bem documentado, com reasoning_effort, enable_thinking e reasoning_content de streaming todos cobertos acima.

Como o qwen3.8-max se compara ao Qwen3-Coder para trabalhos de codificação? São ferramentas diferentes. O Qwen3-Coder é uma linha de modelos de codificação especializada; o qwen3.8-max é o carro-chefe geral que, por acaso, apresenta fortes números de codificação agêntica na própria tabela da Alibaba (86.6 no Terminal Bench 2.1, de acordo com benchmarks executados pelo fornecedor). Se você estiver escolhendo entre eles, teste ambos através da mesma superfície de API: as chamadas são idênticas, exceto pelo ID do modelo.

Conclusão

A API Qwen 3.8 é um dos lançamentos de carro-chefe mais fáceis de adotar. Seu código SDK OpenAI funciona após uma troca de URL base, sua configuração do Claude Code funciona após três variáveis de ambiente, e o preço fixo de $2/$6 significa que você não precisa de uma planilha para prever custos em todo o contexto de 1M. As principais coisas a realmente observar: tokens de raciocínio cobrados como saída no esforço padrão xhigh, e a divisão regional da cota gratuita.

Comece com a cota gratuita de Cingapura, transmita algumas requisições para ver como os deltas de raciocínio se comportam e passe seus próprios prompts por ele antes de confiar em qualquer tabela de benchmark, incluindo a da Alibaba. Configurar tudo como um projeto no Apidog, com regiões como ambientes e ambos os protocolos como requisições salvas, transforma essa avaliação de uma tarde de cURL ad-hoc em algo que toda a sua equipe pode executar novamente quando o próximo modelo for lançado.