Usar API

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

Oferecemos suporte a dois tipos de API para agentes de IA:

  • API compatível com OpenAI: adequada para integração com bibliotecas e interfaces externas, utilizando a estrutura padrão de requisição.
  • API nativa: mais simples e fácil de usar, especialmente quando é necessário obter um resultado rapidamente sem dependências externas.

Exemplos de requisições
Copiar link

API compatível com OpenAI
Copiar link

Exemplo de requisição:

POST https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "temperature": 1,
  "max_tokens": 100,
  "stream": false
}

Exemplo de resposta:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hi! How can I help you?"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 14,
    "total_tokens": 26
  }
}

API nativa
Copiar link

Exemplo de requisição:

POST https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/call
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "message": "Hello",
  "parentmessageid": "3adfea84-bcdb-44b5-8914-92035e75ec24"
}

Exemplo de resposta:

{
  "message": "Hi! How can I help you?",
  "id": "340b7381-2834-4b98-a51c-e68f8d0abd5b",
  "response_id": "ed08981f-126b-49e7-856d-d122b3a53f26"
}

Principais diferenças
Copiar link

Recurso

API compatível com OpenAI

API nativa

Formato da requisição

array messages[]

campo message com parentMessageId

Histórico de mensagens

Não armazenado, enviado na requisição

Armazenado entre requisições (usando parentMessageId)

Respostas em streaming

Suportado (stream: true)

Não suportado

Multimodalidade

Suporte parcial

Apenas texto

Informações de uso

Disponível (usage, model)

Não disponível

Formato da resposta

choices, usage, model, id

message, id, response_id

Qual API escolher
Copiar link

Use a API compatível com OpenAI se você:

  • quiser integrar o agente com bibliotecas externas (por exemplo, LangChain, Open WebUI)
  • já utiliza OpenAI e deseja apenas substituir a URL
  • precisar de estatísticas de uso (tokens, modelo)
  • precisar de respostas em streaming
  • planejar usar mensagens multimodais

Use a API nativa se você:

  • precisar de histórico de mensagens integrado sem enviar contexto explicitamente
  • estiver desenvolvendo uma aplicação simples com poucas dependências externas
  • quiser respostas em um formato simples
  • precisar de uma integração rápida e leve, por exemplo, para um MVP