Acesso à API Qwen tem dois caminhos práticos para equipes que já usam clientes no estilo OpenAI. Você pode chamar o Qwen diretamente pela interface compatível com OpenAI do DashScope do Model Studio da Alibaba Cloud, ou pode manter uma única URL base do roteador Flatkey e usar o Qwen junto dos outros modelos que seu produto já encaminha.
O caminho direto da Alibaba Cloud é específico por região. O caminho da Flatkey usa https://router.flatkey.ai/v1, uma chave Flatkey e um ID de modelo Qwen selecionado do catálogo atual da Flatkey antes de você testar logs, unidades de preço, suporte a recursos e rollback.
Este guia explica como usar o acesso à API Qwen por meio de uma URL base compatível com OpenAI. Ele cobre o que a documentação oficial da Alibaba Cloud confirma, onde a Flatkey altera o modelo operacional e o que verificar antes de mover tráfego de produção.
Resposta rápida: acesso à API Qwen por meio de uma única Base URL do Router
Se o seu app já usa o SDK Python ou JavaScript da OpenAI, o acesso à API Qwen pode começar como uma mudança de configuração, em vez de uma reescrita do SDK do provedor.
| Decisão | Qwen direto no Model Studio | Qwen via Flatkey |
|---|---|---|
| Chave de API | Chave de API DashScope do Alibaba Cloud Model Studio | Chave de API Flatkey |
| Base URL | URL DashScope compatível com OpenAI e específica da região | https://router.flatkey.ai/v1 |
| Objetivo principal | Chamar o Qwen diretamente com sintaxe compatível com OpenAI | Roteie o Qwen junto de outros provedores atrás de uma única chave |
| Escolha de modelo | Modelo Qwen da documentação e da região da conta do Alibaba Cloud | Modelo Qwen da precificação ou do painel da Flatkey |
| Validação | Resposta, suporte a recursos, cobrança do Alibaba Cloud | Resposta, log de uso da Flatkey, unidade de preço, cota, reversão |
Use o endpoint direto do Model Studio quando você precisar apenas do controle da conta Alibaba Cloud para o Qwen. Use a Flatkey quando o Qwen precisar ficar dentro do mesmo fluxo de acesso, roteamento, cota, log de uso e cobrança que GPT, Claude, Gemini, DeepSeek, Seedance, modelos de imagem e outras famílias de modelos.
O que a documentação Qwen da Alibaba Cloud confirma
A Alibaba Cloud documenta que os modelos Qwen no Model Studio oferecem suporte a uma interface compatível com a OpenAI. A instrução oficial de migração é direta: ajuste a chave de API, BASE_URL e o nome do modelo. Esse é o mesmo padrão de migração em três partes que a maioria dos usuários de SDK compatíveis com OpenAI espera.
A documentação oficial lista URLs base específicas por região para chamadas de SDK:
| Region | OpenAI-Compatible Base URL |
|---|---|
| Singapore | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 |
| US (Virginia) | https://dashscope-us.aliyuncs.com/compatible-mode/v1 |
| China (Beijing) | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| Hong Kong (China) | https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1 |
A referência de Chat da OpenAI também documenta o formato completo do endpoint de chat, como POST https://dashscope-us.aliyuncs.com/compatible-mode/v1/chat/completions para chamadas nos EUA. A mesma documentação inclui exemplos de chat sem streaming, streaming, uso no último chunk do stream, chamada de ferramentas, saída JSON, entrada de imagem para modelos com capacidade de visão e opções relacionadas à busca.
Isso não significa que todo modelo Qwen suporte todos os recursos. Significa que o acesso à API Qwen deve ser testado recurso por recurso: primeiro chat básico, depois streaming, ferramentas, JSON, visão, busca ou qualquer endpoint que seu aplicativo realmente use.
Onde o Flatkey muda a configuração do Qwen
O Flatkey muda a superfície operacional em torno do acesso à API do Qwen. Em vez de escolher diretamente uma URL base de região do DashScope em cada aplicativo, você aponta seu cliente compatível com OpenAI para uma única URL base de roteador:
https://router.flatkey.ai/v1Essa rota importa quando o Qwen não é o único modelo na sua stack. O texto público do produto da Flatkey posiciona a plataforma em torno de uma API key, preços claros, visibilidade de uso e um único painel para chaves, uso e roteamento. O suporte ao Qwen para este artigo foi verificado por meio do snapshot ao vivo do catálogo de preços da Flatkey, e não por uma afirmação permanente da página inicial.
O snapshot de preços da Flatkey consultado no dia da publicação para este artigo retornou 638 linhas totais de modelos e 63 linhas com nome Qwen. Dessas linhas Qwen, 28 estavam marcadas como disponíveis no snapshot, e as linhas Qwen expunham openai como um tipo de endpoint suportado. Considere isso como prova datada de 16 de junho de 2026, e não como uma garantia permanente de disponibilidade: confirme o ID atual do modelo Qwen em preços ou no painel antes do tráfego de produção.
Padrão de Migração da URL Base
Mantenha o acesso à API Qwen na configuração em vez de codificar URLs de provedores em todo o seu código.
FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_QWEN_MODEL="replace-with-flatkey-qwen-model-id"
# Valores opcionais diretos do Model Studio para comparação ou reversão.
DASHSCOPE_API_KEY="sk-your-dashscope-key"
DASHSCOPE_BASE_URL="https://dashscope-us.aliyuncs.com/compatible-mode/v1"A distinção importante é a propriedade da rota. Testes diretos do Qwen usam uma chave DashScope e uma URL base regional do DashScope. Testes da Flatkey usam uma chave Flatkey e a URL base do roteador Flatkey. Não misture chaves, URLs base e IDs de modelo entre os dois caminhos.
Template Python para Qwen via Flatkey
Somente template: execute isto com uma chave Flatkey válida e um ID de modelo Qwen da Flatkey confirmado antes de usá-lo em produção.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_QWEN_MODEL"],
messages=[
{
"role": "user",
"content": "Responda com uma frase confirmando que a rota Qwen está configurada.",
}
],
)
print(response.choices[0].message.content)
print(response.usage)A estrutura do código é intencionalmente o uso comum do SDK da OpenAI. O trabalho de produção é escolher o ID de modelo certo, testar seu conjunto de recursos e confirmar que a solicitação aparece nos logs de uso da Flatkey com o modelo, status, uso de tokens e custo esperados.
Modelo de JavaScript para Qwen via Flatkey
Apenas modelo: execute isto com uma chave Flatkey válida e um ID de modelo confirmado do catálogo atual da Flatkey.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.OPENAI_BASE_URL || "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_QWEN_MODEL,
messages: [
{
role: "user",
content: "Responda com uma frase confirmando que a rota do Qwen está configurada.",
},
],
});
console.log(response.choices[0].message.content);
console.log(response.usage);Para equipes que já usam clientes JavaScript compatíveis com OpenAI, isso mantém o acesso à API do Qwen pequeno o suficiente para ser revisado em uma única mudança de configuração. A rota ainda precisa de um teste rápido antes do tráfego real.
Qwen Direto Versus Flatkey: O Que Testar
A escassez de artigos nos resultados de pesquisa atuais não é apenas outra lista de modelos Qwen. A documentação oficial já faz isso. O ponto que falta é uma lista prática de verificação do roteador para decidir quando o Qwen direto é suficiente e quando uma única URL base é o caminho operacional mais limpo.
| Necessidade do Fluxo de Trabalho | Verificação do Qwen Direto | Verificação do Roteador Flatkey |
|---|---|---|
| Chat básico | Use a URL base regional correta do DashScope e o modelo. | Use https://router.flatkey.ai/v1 e um ID de modelo Qwen da Flatkey. |
| Streaming | Teste stream: true e o tratamento final de usage no DashScope. |
Teste os chunks de stream, o comportamento de timeout e o registro final de usage pela Flatkey. |
| Ferramentas/chamada de função | Confirme que o modelo Qwen escolhido suporta o esquema de tool que você envia. | Confirme que o mesmo esquema passa pelo caminho Qwen da Flatkey selecionado. |
| Saída JSON | Teste seu padrão exato de response_format. |
Verifique a compatibilidade do parser e o comportamento de erro pelo roteador. |
| Entrada de visão | Selecione um modelo de visão Qwen e teste o formato do payload de imagem. | Confirme que o modelo da Flatkey aceita a mesma forma de entrada de imagem. |
| Revisão de custo | Consulte a cobrança e os documentos de preços do Alibaba Cloud Model Studio. | Consulte os preços da Flatkey e os logs reais de uso. |
| Roteamento multivendor | Requer configuração separada do provedor para modelos que não sejam Qwen. | Mantenha o Qwen ao lado de outros provedores atrás de uma única chave e dashboard. |
Manual de teste de fumaça
Um teste rápido de acesso à API Qwen deve comprovar tanto o comportamento da API quanto a visibilidade do roteador.
- Escolha um ID de modelo Qwen a partir dos preços atuais da Flatkey ou do painel.
- Crie ou selecione uma chave Flatkey de baixo risco para testes.
- Defina
OPENAI_BASE_URLcomohttps://router.flatkey.ai/v1. - Execute um prompt de chat simples sem streaming.
- Confirme que o formato da resposta funciona com o analisador do seu aplicativo.
- Verifique os logs de uso da Flatkey para modelo, status, uso de tokens e custo.
- Execute um teste de modelo inválido e registre o formato do erro.
- Execute streaming, tools, JSON, search ou vision apenas se o seu aplicativo os usar.
- Defina uma cota pequena antes que o tráfego real seja enviado.
- Mantenha as configurações diretas do DashScope ou do provedor anterior como configuração de reversão até que a rota esteja estável.
O objetivo não é apenas fazer uma resposta da Qwen aparecer. O objetivo é saber para onde a solicitação foi, quanto custou, como as falhas aparecem e quão rápido você pode restaurar a rota anterior.
Erros Comuns
- Usar uma chave de API do DashScope com a URL base do Flatkey, ou uma chave do Flatkey com a URL base do DashScope.
- Copiar um nome de modelo Qwen da documentação da Alibaba Cloud sem confirmar a string do catálogo do Flatkey.
- Assumir que cada parâmetro compatível com OpenAI se comporta da mesma forma nos caminhos direto e roteado.
- Testar apenas chat sem streaming quando a produção usa streaming, ferramentas, JSON, busca ou visão.
- Ignorar o registro de uso e a verificação de preços do Flatkey após uma resposta bem-sucedida.
- Publicar trechos de código com chaves aparentemente reais ou IDs de modelo de produção não testados.
Esses são pequenos detalhes, mas é neles que a maioria das migrações de acesso à API Qwen falha. Um roteador facilita o acesso; ele não elimina a necessidade de testar a forma exata da solicitação.
Como isto se encaixa com os guias de migração Flatkey existentes
Se esta for a sua primeira migração de roteador, comece com o mais amplo guia de migração de API compatível com OpenAI. Ele aborda o padrão de URL base, variáveis de ambiente, testes rápidos, reversão e verificações no painel que se aplicam a qualquer provedor.
Depois, use este guia específico do Qwen para os detalhes do provedor: endpoints regionais do DashScope, seleção de modelo Qwen, streaming e testes de recursos, e a verificação do catálogo Flatkey. Para uma rota de provedor semelhante, compare o guia do roteador compatível com OpenAI da API Gemini.
Perguntas frequentes
Como obtenho acesso à API Qwen?
Você pode obter acesso à API Qwen diretamente pelo Alibaba Cloud Model Studio com uma chave de API DashScope, ou rotear o Qwen por meio do Flatkey com uma chave Flatkey e https://router.flatkey.ai/v1. O caminho direto usa URLs base regionais do DashScope; o caminho via Flatkey mantém o Qwen em um único gateway multissserviço.
A API Qwen é compatível com OpenAI?
O Alibaba Cloud documenta uma interface compatível com OpenAI para modelos Qwen no Model Studio. A migração altera a chave da API, a URL base e o nome do modelo. Ainda é necessário testar, em nível de funcionalidade, streaming, ferramentas, saída JSON, visão, busca e quaisquer parâmetros avançados.
Qual é a URL base compatível com OpenAI direta do Qwen?
Depende da região. O Alibaba Cloud lista URLs base regionais, incluindo https://dashscope-us.aliyuncs.com/compatible-mode/v1 para os EUA (Virgínia), https://dashscope-intl.aliyuncs.com/compatible-mode/v1 para Singapura e https://dashscope.aliyuncs.com/compatible-mode/v1 para a China (Pequim).
Qual URL base devo usar para o Qwen via Flatkey?
Use https://router.flatkey.ai/v1 para o Qwen via Flatkey. Em seguida, escolha um ID de modelo Qwen atual na tabela de preços do Flatkey ou no painel e teste a solicitação antes do tráfego de produção.
Posso usar o mesmo ID de modelo Qwen da documentação do Alibaba Cloud no Flatkey?
Não automaticamente. As strings de modelo, aliases, disponibilidade e suporte ao endpoint podem variar conforme o catálogo e a rota. Escolha o ID do modelo no Flatkey no dia em que fizer o teste e mantenha-o na configuração.
Compatível com OpenAI significa paridade total de recursos?
Não. Compatível com OpenAI geralmente significa que formas comuns de solicitação e resposta funcionam para endpoints compatíveis. Isso não garante comportamento idêntico para cada modelo, parâmetro, endpoint, região, modo de streaming, chamada de ferramenta ou payload multimodal.
Como devo orçar o uso do Qwen por meio de um roteador?
Use a documentação de preços do Alibaba Cloud para o contexto direto do Model Studio e a precificação do Flatkey para uso roteado. Em seguida, verifique o custo real da solicitação nos logs do Flatkey, pois modelo, cache, endpoint e unidades de modalidade podem diferir.
Veja a precificação antes de rotear o tráfego de produção
Acesso à API Qwen por meio de um roteador compatível com OpenAI é um caminho prático de migração quando seu app já usa chamadas de SDK no estilo OpenAI. Mantenha a mudança pequena: atualize a URL base, use uma chave Flatkey, selecione um modelo Qwen atual, execute os testes de smoke e verifique o uso e a precificação antes do rollout.
Veja a precificação para confirmar as opções atuais de modelos Qwen da Flatkey e as unidades de custo antes de enviar tráfego de produção.
