Pular para o conteúdo principal

​
Endpoint

POST https://api.bunny.build/api/v1/ai-chat

​
Autenticação

HeaderObrigatórioValor
X-API-KeySimSua chave de API (bun_...)
Content-TypeSimapplication/json

​
Visão geral

A API de AI Chat aceita um histórico de conversa como um array de mensagens e retorna a resposta do modelo junto com estatísticas de uso de tokens. Cada mensagem carrega um role (user, assistant ou system) e uma string content, permitindo conversas completas com múltiplas rodadas e instruções em nível de sistema.

​
Casos de uso

  • Adicionar chat com IA a qualquer aplicação sem gerenciar infraestrutura de modelos
  • Criar bots de suporte ao cliente com prompts de sistema personalizados
  • Prototipação rápida de funcionalidades conversacionais com uma única requisição POST
  • Criar fluxos de diálogo com múltiplas rodadas em que o contexto anterior molda cada resposta

​
Detalhes

As mensagens são processadas em ordem, portanto o histórico completo da conversa deve ser enviado a cada chamada. O papel system é usado para definir o comportamento ou persona do modelo. São aceitas até 50 mensagens por requisição, e o conteúdo de cada mensagem é limitado a 10.000 caracteres. O uso de tokens é retornado no campo usage quando disponível.

​
Corpo da requisição

CampoTipoObrigatórioDescrição
messagesarraySimLista ordenada de mensagens da conversa (1–50 itens)

​
Objeto de mensagem

CampoTipoObrigatórioDescrição
rolestringSimUm dos valores: user, assistant, system
contentstringSimTexto da mensagem (máximo de 10.000 caracteres)

​
Exemplo

{
  "messages": [
    { "role": "system", "content": "Você é um assistente útil que responde de forma concisa." },
    { "role": "user", "content": "Qual é a capital da França?" }
  ]
}

​
Resposta

​
200 OK

CampoTipoDescrição
replystringResposta gerada pelo modelo
usageobjeto ou nullEstatísticas de uso de tokens, ou null se não disponível
usage.prompt_tokensnúmeroTokens consumidos pelas mensagens de entrada
usage.completion_tokensnúmeroTokens gerados na resposta
usage.total_tokensnúmeroSoma dos tokens de prompt e de conclusão
usage.reasoning_tokensnúmeroTokens usados para raciocínio interno (0 se não aplicável)
Exemplo 
{
  "reply": "A capital da França é Paris.",
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 9,
    "total_tokens": 37,
    "reasoning_tokens": 0
  }
}

​
400 Bad Request

Retornado quando o campo messages está ausente, não é um array, está vazio, excede 50 itens ou contém um papel inválido ou conteúdo muito longo. 
{
  "error": "messages is required and must be an array"
}

{
  "error": "messages[0]: role must be user, assistant, or system"
}

​
401 Unauthorized

{
  "detail": "Missing API key. Include X-API-Key header."
}

​
402 Payment Required

{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}

​
429 Too Many Requests

{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}

​
502 Bad Gateway

Retornado quando o serviço de IA está indisponível ou retorna um erro inesperado. 
{
  "error": "AI service responded with 503"
}

​
Exemplo cURL

curl -X POST https://api.bunny.build/api/v1/ai-chat \
  -H "X-API-Key: bun_sua_chave_api" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "Você é um assistente útil." },
      { "role": "user", "content": "Qual é a capital da França?" }
    ]
  }'