> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /ai-chat

> Envie um histórico de conversa e receba uma resposta gerada por IA. Suporta chats com múltiplas rodadas usando os papéis user, assistant e system.

## 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

```json theme={null}
{
  "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**

```json theme={null}
{
  "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.

```json theme={null}
{
  "error": "messages is required and must be an array"
}
```

```json theme={null}
{
  "error": "messages[0]: role must be user, assistant, or system"
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 429 Too Many Requests

```json theme={null}
{
  "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.

```json theme={null}
{
  "error": "AI service responded with 503"
}
```

## Exemplo cURL

```bash theme={null}
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?" }
    ]
  }'
```