POST /ai-chat

Endpoint

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

Authentication

Header	Required	Value
`X-API-Key`	Yes	Your API key (`bun_...`)
`Content-Type`	Yes	`application/json`

Overview

The AI Chat API accepts a conversation history as an array of messages and returns the model’s reply along with token usage statistics. Each message carries a role (user, assistant, or system) and a content string, enabling full multi-turn conversations and system-level instructions.

Use cases

Add AI-powered chat to any application without managing model infrastructure
Build customer support bots with custom system prompts
Prototype conversational features quickly with a single POST request
Create multi-turn dialogue flows where prior context shapes each reply

Details

Messages are processed in order, so the conversation history must be complete each time you call the API. The system role is used to set behavior or persona for the model. Up to 50 messages are accepted per request, and each message content is limited to 10,000 characters. Token usage is returned in the usage field when available.

Request body

Field	Type	Required	Description
`messages`	array	Yes	Ordered list of conversation messages (1–50 items)

Message object

Field	Type	Required	Description
`role`	string	Yes	One of: `user`, `assistant`, `system`
`content`	string	Yes	Message text (max 10,000 characters)

Example

{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant that replies concisely." },
    { "role": "user", "content": "What is the capital of France?" }
  ]
}

Response

200 OK

Field	Type	Description
`reply`	string	The model’s generated response
`usage`	object or null	Token usage statistics, or `null` if unavailable
`usage.prompt_tokens`	number	Tokens consumed by the input messages
`usage.completion_tokens`	number	Tokens generated in the reply
`usage.total_tokens`	number	Sum of prompt and completion tokens
`usage.reasoning_tokens`	number	Tokens used for internal reasoning (0 if not applicable)

Example

{
  "reply": "The capital of France is Paris.",
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 9,
    "total_tokens": 37,
    "reasoning_tokens": 0
  }
}

400 Bad Request

Returned when the messages field is missing, not an array, empty, exceeds 50 items, or contains an invalid role or oversized content.

{
  "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

Returned when the upstream AI service is unavailable or returns an unexpected error.

{
  "error": "AI service responded with 503"
}

cURL example

curl -X POST https://api.bunny.build/api/v1/ai-chat \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "What is the capital of France?" }
    ]
  }'

Introduction

API Reference

POST /ai-chat

Endpoint

Authentication

Overview

Use cases

Details

Request body

Message object

Example

Response

200 OK

400 Bad Request

401 Unauthorized

402 Payment Required

429 Too Many Requests

502 Bad Gateway

cURL example

​Endpoint

​Authentication

​Overview

​Use cases

​Details

​Request body

​Message object

​Example

​Response

​200 OK

​400 Bad Request

​401 Unauthorized

​402 Payment Required

​429 Too Many Requests

​502 Bad Gateway

​cURL example

Endpoint

Authentication

Overview

Use cases

Details

Request body

Message object

Example

Response

200 OK

400 Bad Request

401 Unauthorized

402 Payment Required

429 Too Many Requests

502 Bad Gateway

cURL example