API compatível com OpenAI

Última atualização em 17 de março de 2026

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.

Autenticação

Para fazer requisições, é necessário um token de API.

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)

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.

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.

Por que a padronização é importante Copiar link

Limitações Copiar link

Uso Copiar link

Autenticação Copiar link

URL base Copiar link

Enviar mensagens para o agente Copiar link

Exemplo de uso do Chat Completions

Exemplo de uso do Text Completions

Papéis (roles) Copiar link

user Copiar link

assistant Copiar link

system Copiar link

Por que a padronização é importante

Limitações

Uso

Autenticação

URL base

Enviar mensagens para o agente

Papéis (roles)

user

assistant

system