Como integrar o Gate.AI: Guia rápido para desenvolvedores

Gate.AI API integração permite que desenvolvedores acessem múltiplos modelos de IA compatíveis com a API OpenAI, possibilitando uma integração unificada de modelos, roteamento e testes, sem a necessidade de manter configurações SDK separadas para cada provedor de modelos. Seja para desenvolver chatbots, ferramentas internas, agentes inteligentes, automação de processos ou scripts de avaliação de modelos, o processo de integração é significativamente simplificado. Este guia abordará a criação de chaves API, roteamento automático, seleção manual de modelos, URL base compatível com OpenAI, testes com primeira requisição e resolução de erros comuns de configuração, excluindo tópicos avançados como governança corporativa, estratégias de cobrança ou arquiteturas de segurança personalizadas.

Pré-requisitos:

• Possuir conta Gate.AI e acesso às configurações do Console.
• Ambiente local configurado com Python, Node.js ou curl.

Quais habilidades você terá após completar este guia?

Ao concluir este guia, você será capaz de criar uma chave API Gate.AI, configurar uma URL base compatível com OpenAI, enviar sua primeira requisição API usando model: "auto" e testar um ID de modelo específico.

Que aplicações os desenvolvedores podem construir usando a API Gate.AI?

Desenvolvedores podem usar a API Gate.AI para integrar múltiplos modelos através de um formato de requisição compatível com OpenAI, com cenários típicos incluindo:

| Tipo de construção | Papel do Gate.AI | Exemplo de saída | | --------------------- | --------------------------------------- | --------------------------------- | | Aplicações de chat | Roteamento de mensagens de usuários para modelos de chat suportados | Assistente de atendimento | | Ferramentas internas | Configuração unificada de API entre equipes | Assistente de escrita/pesquisa AI | | Agentes inteligentes e automação | Conexão de chamadas de modelos e automação de tarefas | Assistente de chamadas de ferramentas | | Teste de modelos | Comparar roteamento "auto" com ID de modelo fixo | Script de avaliação | | Migração de projetos | Substituir URL base compatível com OpenAI existente | Protótipos multi-modelo |

Quando desejar que o Gate.AI escolha automaticamente o modelo, utilize model: "auto"; para comportamentos reprodutíveis em um modelo específico, insira o ID do modelo desejado.

O que você precisa preparar antes de começar?

Antes de iniciar, atenda a duas condições essenciais:

| Condição Necessária | Razão importante | | --------------------- | -------------------------------------------------------------- | | Acesso à conta Gate.AI | Para criar chaves API no Console e verificar configurações de roteamento | | Método de requisição local | Para enviar testes via Python, Node.js ou curl |

Não é necessário escolher todos os modelos inicialmente. Confirme que a chave API e a URL base estão funcionais antes de testar a seleção manual de modelos.

Passo 1: Criar uma chave API Gate.AI

Este passo cria as credenciais usadas para autenticação na API.

Procedimento:

1. Acesse gate.ai.
2. Faça login e autorize.
3. Vá ao Console → Configurações → Chaves API.
4. Clique em Criar chave.
5. Copie imediatamente a chave API e armazene com segurança.

Na área de chaves API, você verá a nova chave. Se o segredo for exibido apenas uma vez, copie antes de fechar a janela de criação.

Passo 2: Selecionar roteamento automático ou escolha manual de modelo

Este passo decide se o Gate.AI irá atribuir automaticamente um modelo ou se você irá especificar um na requisição.

Procedimento:

1. Vá ao Console → Configurações → Roteamento.
2. Verifique se o interruptor de Roteamento automático está ativado.
3. Para que o Gate.AI escolha automaticamente o modelo por requisição, mantenha o roteamento automático ativado.
4. Para especificar manualmente o ID do modelo, desative o roteamento automático e insira o ID na carga da requisição.

| Modo de seleção | Valor do parâmetro na requisição | Cenário de uso | | ------------------- | -------------------------------------------- | -------------------------------------------- | | Roteamento automático | "model": "auto" | Quando desejar que o Gate.AI roteie automaticamente | | Seleção manual de modelo | "model": "anthropic/claude-sonnet-4.6" | Para testes ou uso de um modelo específico |

O roteamento automático é útil para integração rápida e testes gerais; a seleção manual é indicada para avaliações reprodutíveis de um único modelo.

Passo 3: Configurar URL base compatível com OpenAI

Este passo ajusta o cliente estilo OpenAI para apontar para o Gate.AI, ao invés do endpoint padrão do OpenAI.

Use a URL base abaixo:

[URL base]

O formato de autenticação é:

Authorization: Bearer YOUR_API_KEY

A documentação do Gate.AI exige que o caminho da API seja /openai/v1, e não apenas /v1 (até junho de 2026). Insira a URL base completa conforme o exemplo.

| Configuração | Valor | | ------------------- | -------------------------------------------- | | URL base | [insira aqui] | | Método de autenticação | Authorization: Bearer YOUR_API_KEY | | Formato | Compatível com OpenAI | | Endpoint de chat | POST /chat/completions | | Endpoint de modelos | GET /models |

A maioria dos erros de integração ocorre por URL base abreviada ou cópia incorreta da chave API. Confirme esses pontos antes de ajustar o modelo.

Passo 4: Enviar sua primeira requisição API

Este passo testa se a chave API, URL base e o formato de chat compatível com OpenAI funcionam em conjunto.

Exemplo em Python:

python from openai import OpenAI

client = OpenAI( api_key="YOUR_API_KEY", base_url="", )

completion = client.chat.completions.create( model="auto", messages=[ {"role": "system", "content": "Você é um assistente conciso."}, {"role": "user", "content": "Diga olá do Gate.AI."} ], )

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

Exemplo em Node.js:

javascript import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "", });

const completion = await client.chat.completions.create({ model: "auto", messages: [ { role: "system", content: "Você é um assistente conciso." }, { role: "user", content: "Diga olá do Gate.AI." } ], });

console.log(completion.choices[0].message.content);

Exemplo com curl:

bash curl /chat/completions
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{ "model": "auto", "messages": [ {"role": "system", "content": "Você é um assistente conciso."}, {"role": "user", "content": "Diga olá do Gate.AI."} ] }'

Você deve receber uma resposta adequada do assistente. Se ocorrer erro de autenticação, verifique a chave API, sem necessidade de alterar o código imediatamente.

Passo 5: Testar ID de modelo específico

Este passo valida se a seleção manual de modelo funciona ao especificar um ID de modelo.

Altere o parâmetro model de auto para o ID de um modelo suportado, por exemplo:

python from openai import OpenAI

client = OpenAI( api_key="YOUR_API_KEY", base_url="", )

completion = client.chat.completions.create( model="anthropic/claude-sonnet-4.6", messages=[ {"role": "user", "content": "Explique o roteamento de modelos em um parágrafo."} ], )

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

Insira exatamente o nome do modelo conforme a documentação ou lista de modelos do Gate.AI. Erros de digitação podem causar falha na requisição, mesmo com API key e URL corretos.

Como funciona o roteamento automático na requisição API do Gate.AI?

O roteamento automático do Gate.AI funciona ao preencher "model": "auto" na requisição, aliado às configurações de roteamento no console, para que o sistema escolha o modelo automaticamente. Até junho de 2026, as configurações de roteamento podem ser gerenciadas em Console → Configurações → Roteamento.

| Método de roteamento | Local de configuração | Parâmetro na API | | --------------------- | ------------------------------------------ | ---------------------------- | | Roteamento automático | Console → Configurações → Roteamento | "model": "auto" | | Seleção manual de modelo | Corpo da requisição | Especificar ID do modelo | | Controle de estratégia de roteamento | Configurações de roteamento no console | Personalizar comportamento |

Roteamento automático não é o mesmo que omitir o campo de modelo. É necessário definir explicitamente "model": "auto" para ativar o roteamento automático.

Qual método de integração devo escolher?

Escolha de acordo com o ambiente de aplicação:

| Método | Cenário de uso | Mudanças principais | | ------------------------------ | ---------------------------------------------- | ---------------------------------------- | | SDK Python | Backend Python existente ou scripts | Configurar base_url e api_key | | SDK Node.js | Serviços em JavaScript ou TypeScript | Configurar baseURL e apiKey | | curl | Teste rápido manual | Enviar cabeçalhos e payload JSON | | Aplicação compatível com OpenAI | Aplicações que suportam URL base personalizada | Substituir URL base e API key |

Recomendado começar com curl para validação rápida, depois integrar com SDKs Python ou Node.js na aplicação real.

Quais são as causas comuns de falha na requisição API do Gate.AI?

Para solucionar problemas, verifique:

| Sintoma | Causa provável | Solução | | ------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------- | | 401 ou chave API inválida | Chave ausente, expirada, incorreta ou sem Bearer | Recrie ou copie a chave, use Authorization: Bearer YOUR_API_KEY | | Modelo não encontrado | ID de modelo incorreto ou não disponível na conta | Consulte a documentação de modelos do Gate.AI ou teste com model: "auto" | | Código compatível com OpenAI falha imediatamente | URL base incompleta ou apenas /v1 | Use URL completa conforme exemplo | | Roteamento automático não funciona como esperado | Roteamento desativado ou configuração incorreta | Verifique se o roteamento automático está ativado no console | | Resposta vazia ou erro | Formato de requisição incorreto ou modelo não suportado | Teste primeiro com requisição de chat simples, depois adicione parâmetros gradualmente |

Comece verificando autenticação, URL base e ID do modelo. A maioria dos problemas de integração rápida pode ser resolvida com esses passos.

Quais configurações podem ser feitas após a primeira requisição bem-sucedida?

Após sucesso na primeira requisição, o desenvolvedor pode expandir a integração para:

• Configurar comportamentos de roteamento de modelos no console do Gate.AI
• Ver modelos disponíveis e fixar um ID de modelo para testes de produção
• Comparar preços e escolher modelos adequados para alta concorrência

Perguntas frequentes

Por que usar preferencialmente model: "auto"?

Usar "auto" valida rapidamente a chave API, URL base, formato de requisição e roteamento. Após confirmação, teste um ID de modelo específico.

Posso usar SDK OpenAI existente para chamar Gate.AI?

Sim. Gate.AI suporta o formato compatível com OpenAI, basta configurar a chave API do Gate.AI e substituir a URL base.

Por que a requisição falha ao usar um modelo específico?

O ID do modelo pode não existir, estar incorreto ou não ser suportado pela conta. Verifique o ID na documentação do Gate.AI e tente novamente.

Ao usar um modelo específico, preciso desativar o roteamento automático?

Não necessariamente. Para selecionar manualmente, envie o ID do modelo na requisição. Se o comportamento não for o esperado, verifique as configurações de roteamento no console.