Nota do autor: Detalhamos as 3 rotas de Base URL e os 3 nós de domínio da plataforma APIYI para ajudar os desenvolvedores a configurar tudo corretamente de primeira e evitar problemas comuns.
Ao configurar a API de um Modelo de Linguagem Grande, preencher a Base URL incorretamente é um dos problemas mais frequentes. Diferentes fabricantes de modelos adotam especificações de caminho distintas — a OpenAI usa /v1, a Anthropic Claude usa o domínio raiz e o Google Gemini usa /v1beta — e, se você não conhecer essas diferenças, a invocação do modelo certamente falhará.
A plataforma APIYI é totalmente compatível com essas três especificações de caminho e oferece 3 nós de domínio (principal nacional, reserva nacional e exclusivo internacional) para garantir um acesso estável em todo o mundo. Este artigo usará tabelas claras e exemplos de código para ajudar você a configurar todos os cenários de uma só vez.
Valor central: Ao terminar de ler este artigo, você dominará o método completo de configuração da Base URL da APIYI e não perderá mais tempo de depuração devido a erros de caminho.
Pontos principais da Base URL da APIYI
| Ponto | Descrição | Valor |
|---|---|---|
| 3 especificações de caminho | /v1 genérico, domínio raiz para Claude, /v1beta para Gemini |
Uma plataforma compatível com todos os SDKs principais |
| 3 nós de domínio | Principal (China), Backup (China), Exclusivo (Exterior) | Baixa latência global + alta disponibilidade |
| Formato compatível com OpenAI | Use o caminho /v1 para invocar GPT, DeepSeek, Llama, etc. |
Migre alterando apenas uma linha de base_url |
| Conexão direta via SDK nativo | Claude e Gemini podem usar SDKs oficiais diretamente, sem conversão | Integração com custo zero de adaptação |
Detalhes das especificações de caminho da Base URL da APIYI
Diferentes fornecedores de IA escolheram estilos de caminho distintos ao projetar suas APIs. Isso não é aleatório, mas sim uma convenção rígida dentro dos SDKs de cada empresa:
Linha OpenAI (/v1): A OpenAI usou o prefixo de versão /v1 na URL desde o início. Seu SDK Python concatena diretamente o base_url que você definiu (contendo /v1) com o caminho do recurso (como /chat/completions). Todos os modelos compatíveis com OpenAI — série GPT, DeepSeek, Llama, Qwen, MiniMax, etc. — seguem essa convenção.
Linha Anthropic (domínio raiz): A Anthropic escolheu uma abordagem diferente — o SDK concatena internamente o caminho /v1/messages, portanto, o base_url só precisa conter o domínio raiz, sem o /v1. Se você inserir /v1 por engano, o SDK montará /v1/v1/messages, resultando em um erro 404.
Linha Google Gemini (/v1beta): O Google costuma usar /v1beta para identificar APIs que ainda não atingiram a GA (General Availability). O formato de endpoint do Gemini é /v1beta/models/{model}:generateContent, e o SDK também gerencia a concatenação de caminhos automaticamente.
Seleção de nós de domínio da Base URL da APIYI
A APIYI oferece 3 nós de domínio para cobrir diferentes ambientes de rede:
| Nó | Domínio | Cenário de uso | Descrição |
|---|---|---|---|
| Principal (China) | api.apiyi.com |
Servidores na China, desenvolvimento local | Recomendado, menor latência |
| Backup (China) | b.apiyi.com |
Alternativa em caso de falha no nó principal | Backup para garantir a continuidade do negócio |
| Exclusivo (Exterior) | vip.apiyi.com |
Implantação em servidores no exterior | Otimização de rota internacional, conexão direta de baixa latência |
🎯 Sugestão de escolha: Usuários na China devem priorizar o uso de
api.apiyi.come configurarb.apiyi.comcomo fallback no código. Serviços implantados no exterior devem usar diretamente ovip.apiyi.com. Todos os nós possuem funcionalidades idênticas, diferenciando-se apenas pelas rotas de rede.
Configuração rápida da Base URL da APIYI
Cenário 1: Invocar modelos compatíveis com OpenAI (GPT / DeepSeek / Llama, etc.)
Regra de caminho: Domínio + /v1
import openai
client = openai.OpenAI(
api_key="SUA_CHAVE_API",
base_url="https://api.apiyi.com/v1" # Principal (China) + /v1
)
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Olá!"}]
)
print(response.choices[0].message.content)
Cenário 2: Invocar modelos Claude (SDK da Anthropic)
Regra de caminho: Domínio (domínio raiz, sem /v1)
import anthropic
client = anthropic.Anthropic(
api_key="SUA_CHAVE_API",
base_url="https://api.apiyi.com" # Domínio raiz, sem sufixo de caminho
)
message = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=[{"role": "user", "content": "Olá!"}]
)
print(message.content[0].text)
Cenário 3: Invocar modelos Gemini (SDK Google GenAI)
Regra de caminho: Domínio + /v1beta
from google import genai
client = genai.Client(
api_key="SUA_CHAVE_API",
http_options={"api_version": "v1beta", "base_url": "https://api.apiyi.com"}
)
response = client.models.generate_content(
model="gemini-2.5-pro",
contents="Olá!"
)
print(response.text)
Dica: Obtenha créditos de teste gratuitos através da APIYI (apiyi.com). Você pode configurar e validar os três cenários acima em menos de 5 minutos.
Guia Rápido de Configuração da Base URL da APIYI
Aqui estão todas as combinações de domínio × caminho. Basta copiar e usar:
Configuração da Base URL da APIYI: Modelos compatíveis com OpenAI
| Nó de Domínio | Base URL | Modelos Aplicáveis | SDK Aplicável |
|---|---|---|---|
| Principal (BR) | https://api.apiyi.com/v1 |
GPT, DeepSeek, Llama, Qwen, MiniMax, etc. | OpenAI Python/Node SDK |
| Backup (BR) | https://b.apiyi.com/v1 |
Mesmo acima | Mesmo acima |
| Exclusivo (Intl) | https://vip.apiyi.com/v1 |
Mesmo acima | Mesmo acima |
Configuração da Base URL da APIYI: Modelos Claude
| Nó de Domínio | Base URL | Modelos Aplicáveis | SDK Aplicável |
|---|---|---|---|
| Principal (BR) | https://api.apiyi.com |
Claude Opus 4.6, Sonnet 4.6, Haiku, etc. | Anthropic Python/TS SDK |
| Backup (BR) | https://b.apiyi.com |
Mesmo acima | Mesmo acima |
| Exclusivo (Intl) | https://vip.apiyi.com |
Mesmo acima | Mesmo acima |
Configuração da Base URL da APIYI: Modelos Gemini
| Nó de Domínio | Base URL | Modelos Aplicáveis | SDK Aplicável |
|---|---|---|---|
| Principal (BR) | https://api.apiyi.com/v1beta |
Gemini 2.5 Pro, 2.5 Flash, etc. | Google GenAI SDK |
| Backup (BR) | https://b.apiyi.com/v1beta |
Mesmo acima | Mesmo acima |
| Exclusivo (Intl) | https://vip.apiyi.com/v1beta |
Mesmo acima | Mesmo acima |
🎯 Dica de configuração: As diferenças entre os três caminhos são determinadas pela implementação interna de cada SDK, não sendo uma exigência específica da APIYI. Lembre-se desta regra: OpenAI usa /v1, Claude não usa, e Gemini usa /v1beta — assim você não errará na configuração.
Erros Comuns e Soluções na Base URL da APIYI
Resumo de erros comuns:
| Sintoma de Erro | Causa Provável | Solução |
|---|---|---|
| 404 Not Found | SDK da OpenAI sem /v1, ou SDK da Anthropic com /v1 extra |
Verifique se o caminho corresponde à especificação do SDK |
| 400 Bad Request | Versão do caminho do SDK Gemini incompatível | Confirme o uso de /v1beta |
| Connection Timeout | Nó de domínio mal selecionado | Use api.apiyi.com para Brasil, vip.apiyi.com para exterior |
| SSL Error | Prefixo https:// ausente |
Todos os nós devem usar HTTPS |
Erro de barra dupla // |
Barra / extra no final da base_url |
Remova a barra final |
Perguntas Frequentes
Q1: Ao usar o SDK da OpenAI para invocar modelos Claude, qual Base URL devo preencher?
Se você estiver usando o SDK da OpenAI para invocar o Claude (através da interface compatível com OpenAI da APIYI), preencha a Base URL com https://api.apiyi.com/v1, exatamente como faria para invocar o GPT. Você só precisa usar o domínio raiz ao utilizar o SDK oficial da Anthropic. A diferença fundamental está em qual SDK você está utilizando, e não em qual modelo você está invocando.
Q2: Existe diferença nas funcionalidades dos três nós de domínio?
As funcionalidades são exatamente as mesmas; a diferença reside apenas na otimização da rota de rede. O api.apiyi.com possui a menor latência no território nacional, o vip.apiyi.com tem a menor latência no exterior, e o b.apiyi.com serve como um nó de recuperação de desastres (backup) nacional. Recomendamos configurar um mecanismo de fallback no seu código para que, caso o nó principal atinja o tempo limite, ele alterne automaticamente para o nó de backup.
Q3: Como verificar rapidamente se a configuração da Base URL está correta?
Recomendamos utilizar a plataforma APIYI para a verificação:
- Acesse apiyi.com, crie uma conta e obtenha sua chave API.
- Utilize o exemplo de código deste artigo, substitua
YOUR_API_KEYe execute. - Se a resposta for normal, a configuração está correta; se retornar 404 ou 400, verifique se o caminho corresponde às especificações do SDK.
Resumo
Pontos principais para a configuração da Base URL na APIYI:
- Regras de caminho: O SDK da OpenAI usa
/v1, o SDK da Anthropic usa o domínio raiz (sem sufixo de caminho) e o SDK do Google GenAI usa/v1beta. - Seleção de domínio: Priorize
api.apiyi.compara uso nacional,vip.apiyi.compara o exterior eb.apiyi.comcomo backup. - Dicas para evitar erros: Não adicione
/v1ao SDK da Anthropic, não esqueça o/v1no SDK da OpenAI e não adicione uma barra (slash) ao final.
Lembre-se da regra: OpenAI leva /v1, Claude não leva, e Gemini leva /v1beta — assim você não errará na configuração.
Recomendamos obter créditos gratuitos no apiyi.com para testes rápidos. A plataforma é compatível com os três padrões de caminho e suporta a invocação do modelo de todos os principais modelos do mercado.
📚 Referências
-
Documentação da API da OpenAI: Instruções para acesso à API e uso do SDK
- Link:
platform.openai.com/docs/api-reference - Descrição: Referência oficial da API da OpenAI, para entender a especificação do caminho /v1
- Link:
-
Documentação da API da Anthropic: Guia de acesso ao modelo Claude
- Link:
docs.anthropic.com/en/api/getting-started - Descrição: Para entender a especificação do base_url do SDK da Anthropic
- Link:
-
Google AI for Developers: Instruções de acesso à API Gemini
- Link:
ai.google.dev/gemini-api/docs - Descrição: Para entender o caminho /v1beta e a configuração do SDK GenAI
- Link:
-
Documentação da plataforma APIYI: Guia de acesso rápido e configuração
- Link:
docs.apiyi.com - Descrição: Obtenção de chave API, lista de modelos e configuração de múltiplos nós
- Link:
Autor: Equipe técnica da APIYI
Troca técnica: Sinta-se à vontade para discutir na seção de comentários. Para mais materiais, acesse a documentação da APIYI em docs.apiyi.com
