API compatível com OpenAI

A API compatível com OpenAI fornece uma estrutura unificada de requisição e resposta para diferentes provedores de IA. Em vez de lidar com dezenas de formatos diferentes, você trabalha com um único padrão compatível com SDKs, bibliotecas e interfaces.

Por que a padronização é importante

Considere duas APIs nativas: agent.hostman.com e uma hipotética api.somerandomai.com. Vamos ver como o envio de mensagens é implementado.

Mesmo para a mesma tarefa, as estruturas de requisição podem diferir significativamente. Por exemplo, uma API usa parent_message_id para manter o contexto, enquanto outra usa um objeto aninhado:

"context": {
 "thread_id": "abc123",
 "reply_to": "msg789"
}

Além disso, na nossa API, as configurações são definidas por meio de uma requisição separada, enquanto na API de terceiros elas são incluídas no objeto settings em cada mensagem.

Como resultado, você precisaria:

• escrever um cliente separado para cada API;
• aprender os nomes dos campos e o comportamento de cada API;
• testar tudo do zero.

A API compatível com OpenAI resolve esse problema. A estrutura é sempre a mesma: um array messages com campos role e content, além de parâmetros padrão (model, temperature, max_tokens). As diferenças ficam apenas na URL e no nome do modelo.

Benefícios:

• Integração rápida com qualquer software que suporte a API da OpenAI
• Suporte a bibliotecas populares (por exemplo, LangChain)
• Funciona com interfaces prontas (por exemplo, Open WebUI)
• Esforço mínimo ao migrar da OpenAI

Limitações

A implementação atual não é totalmente compatível com a OpenAI.

Não suportado:

• Embeddings: o endpoint /v1/embeddings não está disponível
• Fine-tuning: treinamento e customização de modelos
• Images API: geração de imagens
• Audio API: conversão de fala para texto e texto para fala (exceto mensagens de áudio no chat)
• Files API: upload e gerenciamento de arquivos
• Assistants API: criação e gerenciamento de assistentes
• Web search: busca e obtenção de dados da internet

Observações de implementação:

• O parâmetro model nas requisições é ignorado; é utilizado o modelo definido nas configurações do agente.
• Alguns parâmetros podem ser ignorados dependendo do modelo selecionado para o agente.
• O prompt definido nas configurações do agente é aplicado às requisições sem prompt explícito.

Uso

Vamos ver como usar a API compatível com OpenAI.

Você pode encontrar todos os métodos disponíveis na documentação.

Autenticação

Independentemente do tipo de API (privada ou pública), é necessário um token de API para as requisições.

Inclua o token no cabeçalho da requisição:

Authorization: Bearer $TOKEN

Nos exemplos em cURL, você pode:

• informar o token manualmente substituindo $TOKEN pelo seu token real em cada requisição; ou
• usar uma variável de ambiente para não precisar inseri-lo todas as vezes:

export TOKEN=your_access_token

A variável $TOKEN será então substituída automaticamente.

Nos exemplos em Python e Node.js, o token é representado como {{token}}. Recomendamos armazená-lo em variáveis de ambiente ou arquivos de configuração, em vez de deixá-lo no código, para evitar vazamentos.

URL base

A API também requer uma URL base, que pode ser encontrada na aba Dashboard do painel de controle do agente.

Enviar mensagens para o agente

Dois métodos são suportados: Chat Completions e Text Completions. O método Text Completions está obsoleto e é mantido apenas para compatibilidade com versões anteriores; não é recomendado.

Exemplo de uso do Chat Completions

POST /api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions

cURL:

curl --request POST \
  --url https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{ "model": "gpt-4.1", "messages": [ { "role": "user", "content": "Hello!" } ], "temperature": 1, "max_tokens": 100, "stream": false }'

Python:

import requests

url = "https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions"

payload = {
    "model": "gpt.1",
    "messages": [
        {
            "role": "user",
            "content": "Hello!"
        }
    ],
    "temperature": 1,
    "max_tokens": 100,
    "stream": False
}
headers = {
    "authorization": "Bearer {{token}}",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Node.js:

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions',
  headers: {authorization: 'Bearer {{token}}', 'content-type': 'application/json'},
  body: {
    model: 'gpt.1',
    messages: [{role: 'user', content: 'Hello!'}],
    temperature: 1,
    max_tokens: 100,
    stream: false
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Parâmetros:

• model: opcional, ignorado (para compatibilidade)
• messages: array de mensagens:
  • role: papel do remetente (user, assistant, system)
  • content: texto da mensagem
• temperature: nível de criatividade da resposta
• max_tokens: limite de tamanho da resposta
• stream: saída em streaming (true/false)

Para modelos GPT-5, max_tokens é substituído por max_completion_tokens, e o uso de temperature gerará um erro.

Parâmetros adicionais podem variar dependendo do modelo. Ao montar uma requisição, consulte os parâmetros disponíveis no painel de controle para o modelo selecionado: se um parâmetro estiver presente no painel, ele é suportado via API.

Exemplo de resposta:

{
  "id": "fc8cd652-af12-4a89-8ef7-490a0526e8d3",
  "object": "chat.completion",
  "created": 1757601532,
  "model": "gpt-4.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you? 😊"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  }
}

Exemplo de uso do Text Completions

POST /api/v1/cloud-ai/agents/{{agent_id}}/v1/completions

cURL:

curl --request POST \
  --url https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{ "prompt": "Hello!", "model": "gpt-4.1", "max_tokens": 100, "temperature": 0.7, "top_p": 0.9, "n": 1, "stream": false, "logprobs": null, "echo": false, "stop": [ "\n" ], "presence_penalty": 0, "frequency_penalty": 0, "best_of": 1, "user": "hostman" }'

Python:

import requests

url = "https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/completions"

payload = {
    "prompt": "Hello!",
    "model": "4.1",
    "max_tokens": 100,
    "temperature": 0.7,
    "top_p": 0.9,
    "n": 1,
    "stream": False,
    "logprobs": None,
    "echo": False,
    "stop": [" "],
    "presence_penalty": 0,
    "frequency_penalty": 0,
    "best_of": 1,
    "user": "hostman"
}
headers = {
    "authorization": "Bearer {{token}}",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Node.js:

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/completions',
  headers: {authorization: 'Bearer {{token}}', 'content-type': 'application/json'},
  body: {
    prompt: 'Hello!',
    model: 'gpt-4.1',
    max_tokens: 100,
    temperature: 0.7,
    top_p: 0.9,
    n: 1,
    stream: false,
    logprobs: null,
    echo: false,
    stop: ['\n'],
    presence_penalty: 0,
    frequency_penalty: 0,
    best_of: 1,
    user: 'hostman'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Parâmetros:

• prompt: texto da requisição
• model: ignorado, incluído para compatibilidade
• max_tokens: limite de tamanho da resposta
• temperature: nível de criatividade
• top_p: amostragem por probabilidade
• n: número de respostas (ignorado)
• stream: saída em streaming

Outros parâmetros (logprobs, echo, stop, presence_penalty, frequency_penalty, best_of, user) são parcialmente suportados, principalmente por compatibilidade.

Exemplo de resposta:

{
  "id": "7f967459-428c-46ad-87f0-213ff951024d",
  "object": "text_completion",
  "created": 1757601892,
  "model": "gpt-4.1",
  "choices": [
    {
      "text": "Hello! How can I help you? 😊",
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  },
  "response_id": "ea9aa124-0c51-467c-9ab6-218ab4ec65e7"
}

Papéis (roles)

Em Chat Completions, cada mensagem inclui um role. Existem três papéis:

• user: requisição do usuário
• assistant: resposta da IA
• system: prompt do sistema

user

O papel user é usado para enviar solicitações comuns do usuário para a IA.

Exemplo:

 {
  "role": "user",
  "content": "What is 2+5?"
}

assistant

Esse papel indica a resposta da IA a uma mensagem anterior.

Importante: na API compatível com OpenAI, o histórico da conversa deve ser incluído em cada requisição. Inclua tanto as mensagens do usuário quanto as respostas da IA para manter o contexto.

Exemplo:

curl --request POST \
  --url https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "model": "gpt-4",
    "messages": [
      { "role": "user", "content": "What is 2+5? Provide only the answer, no formatting." },
      { "role": "assistant", "content": "7" },
      { "role": "user", "content": "Now multiply the result by 2. Provide only the answer, no formatting." }
    ]
  }'

A requisição inclui a pergunta e resposta anteriores, marcando as mensagens como "role": "user" ou "role": "assistant". A última mensagem do usuário fica sem resposta; é para ela que o modelo irá gerar uma nova resposta.

Exemplo de resposta: 

{
  "index": 0,
  "message": {
    "role": "assistant",
    "content": "14",
    "refusal": null,
    "annotations": []
  },
  "finish_reason": "stop"
}

system

O papel system define o comportamento do agente: estilo, tom, restrições e objetivos. Geralmente é a primeira mensagem no array messages. Consulte o artigo sobre system prompts para mais detalhes.

Observando o exemplo de uso do papel assistant, é possível notar que a instrução é repetida nas requisições do usuário:

Provide only the answer, no formatting

Essa duplicação pode ser evitada especificando a instrução uma única vez no prompt do sistema.

Exemplo:

curl --request POST \
  --url https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "model": "gpt-4",
    "messages": [
      { "role": "system", "content": "When answering questions, provide only the calculation result, without any formatting." },
      { "role": "user", "content": "What is 2+5?" },
      { "role": "assistant", "content": "7" },
      { "role": "user", "content": "Now multiply the result by 2" }
    ]
  }'

Agora o modelo seguirá a instrução mesmo que ela não seja repetida em cada mensagem do usuário.