AI Gateway

O AI Gateway é uma API para trabalhar diretamente com modelos de linguagem sem passar por agentes de IA.

Diferente da API compatível com OpenAI e da API nativa, o AI Gateway não oferece recursos de nível de agente, como:

• RAG
• MCP
• Configurações de sistema (system prompt, temperatura, limites de tamanho de resposta)

O AI Gateway é a escolha certa quando você precisa trabalhar diretamente com os modelos, sem nenhuma lógica de agente. Por exemplo:

• Você está construindo sua própria lógica em cima dos modelos (RAG personalizado, integrações com MCP)
• Você precisa de um único ponto de acesso para vários modelos
• Você já usa o OpenAI SDK e quer alternar entre modelos sem alterar o código

AI Gateway vs API compatível com OpenAI

Recomendamos usar o OpenAI SDK para trabalhar com a API, ele abstrai as diferenças e simplifica a integração.

Os métodos e recursos suportados dependem do modelo utilizado. Por exemplo, o endpoint responses só está disponível para modelos com suporte a raciocínio (reasoning).

O AI Gateway não suporta:

• Files API para upload e gerenciamento de arquivos
• Fine-tuning para treinar e personalizar modelos
• Video API para trabalhar com vídeo

Conectar ao AI Gateway

Copiar link

Para se conectar ao AI Gateway, acesse a aba Gateway de IA na seção Agentes de IA.

Criar uma chave de API

Copiar link

O AI Gateway usa chaves separadas, não vinculadas às chaves de API da sua conta.

Para criar uma chave:

1. Acesse Agentes de IA → Gateway de IA.
2. Clique em Criar chave.
3. Defina um nome para a chave e selecione o período de validade.
4. (Opcional) Adicione uma descrição que será exibida no painel.
5. (Opcional) Selecione o projeto.
6. Clique em Criar.

7. Copie a chave gerada e guarde-a em um local seguro.

Excluir uma chave de API

Copiar link

Para excluir uma chave de API:

1. Acesse Agentes de IA → Gateway de IA.
2. Abra a aba Chaves de API.
3. Clique no menu de três pontos ao lado da chave que deseja remover.
4. Clique em Excluir.
5. Confirme a ação.

Obter os dados de conexão

Copiar link

Você encontra os dados de conexão na aba Conexão.

1. Acesse Agentes de IA → Gateway de IA.
2. Abra a aba Conexão.
3. Selecione um modelo e uma linguagem de programação. A interface mostrará o preço dos tokens de entrada e saída para o modelo escolhido.
4. Copie o exemplo de código de conexão e o comando para instalar a biblioteca OpenAI.

Exemplo de uso

Copiar link

Recomendamos usar o OpenAI SDK para trabalhar com o AI Gateway, isso elimina a necessidade de enviar requisições HTTP manualmente e torna a integração muito mais simples.

SDKs disponíveis:

• Python
• Node.js
• Java
• Go

A lista completa de SDKs está disponível no repositório da OpenAI.

Os exemplos abaixo usam Python e a biblioteca openai. Instale com pip:

pip install openai

Enviar uma requisição

Copiar link

Use o método Chat Completions para enviar mensagens. As mensagens são passadas no array messages.

Cada mensagem contém:

• role: o papel de quem envia (user, assistant, system)
• content: o texto da mensagem

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai-api.hostman.com/v1"
)

response = client.chat.completions.create(
    model="MODEL_NAME",
    messages=[
        {
            "role": "system",
            "content": "Responda de forma breve e direta.",
        },
        {
            "role": "user",
            "content": "Explique o que é Kubernetes",
        },
    ],
)

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

Parâmetros:

• api_key: sua chave de API do AI Gateway. Substitua pelo valor da sua chave.
• base_url: a URL base para conexão com o AI Gateway.
• model: o nome do modelo que você quer usar.
• messages: um array de mensagens com roles e textos.

Enviar uma requisição com histórico de mensagens

Copiar link

Para preservar o contexto da conversa, envie as mensagens anteriores no array messages:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai-api.hostman.com/v1"
)

response = client.chat.completions.create(
    model="MODEL_NAME",
    messages=[
        {
            "role": "system",
            "content": "Responda apenas com frases curtas.",
        },
        {
            "role": "user",
            "content": "Quanto é 2 + 5?",
        },
        {
            "role": "assistant",
            "content": "7",
        },
        {
            "role": "user",
            "content": "Agora multiplique o resultado por 2",
        },
    ],
)

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

Neste exemplo, as mensagens anteriores (assistant e user) são incluídas para preservar o contexto da conversa.

Enviar uma requisição (Responses API)

Copiar link

A Responses API é uma forma mais nova de trabalhar com os modelos. Ela simplifica a estrutura da requisição e não exige a criação explícita de um array messages.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai-api.hostman.com/v1"
)

response = client.responses.create(
    model="MODEL_NAME",
    instructions="Responda de forma breve e direta.",
    input="Explique o que é Kubernetes"
)

print(response.output_text)

Parâmetros:

• model: o nome do modelo que você quer usar
• instructions: instruções para o modelo (equivalente a um system prompt)
• input: o texto da requisição

Enviar uma requisição com histórico de mensagens (Responses API)

Copiar link

Para preservar o contexto da conversa usando a Responses API, envie o previous_response_id, que é o ID da resposta anterior.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai-api.hostman.com/v1"
)

response = client.responses.create(
    model="MODEL_NAME",
    instructions="Responda apenas com frases curtas.",
    input="Quanto é 2 + 5?"
)

next_response = client.responses.create(
    model="MODEL_NAME",
    instructions="Responda apenas com frases curtas.",
    previous_response_id=response.id,
    input="Agora multiplique o resultado por 2"
)

print(next_response.output_text)

Neste exemplo, a primeira requisição retorna um objeto de resposta contendo um id único. Esse id é enviado como previous_response_id na próxima requisição, permitindo continuar a conversa sem reenviar todo o histórico de mensagens.

O parâmetro model deve ser informado em todas as requisições, inclusive nas chamadas seguintes que usam previous_response_id.

Listar os modelos disponíveis

Copiar link

O AI Gateway permite obter a lista de modelos disponíveis:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai-api.hostman.com/v1"
)

models = client.models.list()

for model in models.data:
    print(model.id)

O método models.list() retorna uma lista de modelos que podem ser usados no parâmetro model.

Usar embeddings

Copiar link

Embeddings convertem texto em uma representação vetorial. Isso é útil para busca semântica, clusterização ou RAG.

O AI Gateway disponibiliza o modelo openai/text-embedding-3-large para gerar embeddings.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai-api.hostman.com/v1"
)

response = client.embeddings.create(
    model="openai/text-embedding-3-large",
    input="Texto para vetorizar",
)

print(response.data[0].embedding)

O método retorna a representação vetorial do texto enviado.