POST /ai-chat

Endpoint

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

Autenticação

Header	Obrigatório	Valor
`X-API-Key`	Sim	Sua chave de API (`bun_...`)
`Content-Type`	Sim	`application/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

Campo	Tipo	Obrigatório	Descrição
`messages`	array	Sim	Lista ordenada de mensagens da conversa (1–50 itens)

Objeto de mensagem

Campo	Tipo	Obrigatório	Descrição
`role`	string	Sim	Um dos valores: `user`, `assistant`, `system`
`content`	string	Sim	Texto 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

Campo	Tipo	Descrição
`reply`	string	Resposta gerada pelo modelo
`usage`	objeto ou null	Estatísticas de uso de tokens, ou `null` se não disponível
`usage.prompt_tokens`	número	Tokens consumidos pelas mensagens de entrada
`usage.completion_tokens`	número	Tokens gerados na resposta
`usage.total_tokens`	número	Soma dos tokens de prompt e de conclusão
`usage.reasoning_tokens`	número	Tokens 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?" }
    ]
  }'

Introdução

Referência da API

POST /ai-chat

Endpoint

Autenticação

Visão geral

Casos de uso

Detalhes

Corpo da requisição

Objeto de mensagem

Exemplo

Resposta

200 OK

400 Bad Request

401 Unauthorized

402 Payment Required

429 Too Many Requests

502 Bad Gateway

Exemplo cURL

​Endpoint

​Autenticação

​Visão geral

​Casos de uso

​Detalhes

​Corpo da requisição

​Objeto de mensagem

​Exemplo

​Resposta

​200 OK

​400 Bad Request

​401 Unauthorized

​402 Payment Required

​429 Too Many Requests

​502 Bad Gateway

​Exemplo cURL

Endpoint

Autenticação

Visão geral

Casos de uso

Detalhes

Corpo da requisição

Objeto de mensagem

Exemplo

Resposta

200 OK

400 Bad Request

401 Unauthorized

402 Payment Required

429 Too Many Requests

502 Bad Gateway

Exemplo cURL