Skip to main content

​
Endpoint

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

​
Authentication

HeaderRequiredValue
X-API-KeyYesYour API key (bun_...)
Content-TypeYesapplication/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

FieldTypeRequiredDescription
messagesarrayYesOrdered list of conversation messages (1–50 items)

​
Message object

FieldTypeRequiredDescription
rolestringYesOne of: user, assistant, system
contentstringYesMessage 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

FieldTypeDescription
replystringThe model’s generated response
usageobject or nullToken usage statistics, or null if unavailable
usage.prompt_tokensnumberTokens consumed by the input messages
usage.completion_tokensnumberTokens generated in the reply
usage.total_tokensnumberSum of prompt and completion tokens
usage.reasoning_tokensnumberTokens 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?" }
    ]
  }'