API Documentation

Complete reference for the AIBuddy Unified AI Gateway. One API key, all AI models.

Authentication

Include your AIBuddy API key in any request using one of these methods:

Get your API key at aibuddy.life/my-account.

Base URL

https://api.aibuddy.life/v2

Quick Start

Chat (Smart Routing)

curl -X POST "https://api.aibuddy.life/v2/chat" \
  -H "X-Api-Key: aibuddy_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello, build me a React component"}
    ],
    "language": "typescript"
  }'

Image Generation

curl -X POST "https://api.aibuddy.life/v2/image/generate" \
  -H "X-Api-Key: aibuddy_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic city skyline at sunset, cyberpunk style",
    "size": "1024x1024",
    "quality": "hd"
  }'

Video Generation (Async)

curl -X POST "https://api.aibuddy.life/v2/video/generate" \
  -H "X-Api-Key: aibuddy_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A drone flyover of mountain peaks at dawn",
    "model": "veo-3.1-generate-preview"
  }'

# Poll for result
curl "https://api.aibuddy.life/v2/tasks/task_video_abc123" \
  -H "X-Api-Key: aibuddy_your_key"

POST /v2/chat

Request Body

{
  "success": true,
  "response": "Here's your implementation...",
  "thinking": "Extended thinking output (when enabled)",
  "usage": { "input_tokens": 500, "output_tokens": 2000 },
  "model": "gpt-5.3-codex",
  "provider": "openai",
  "api_cost": 0.018,
  "remaining_credits": 45.50,
  "routing": {
    "provider": "openai",
    "model": "gpt-5.3-codex",
    "reason": "smart_routing"
  },
  "duration_ms": 3200,
  "request_id": "uuid"
}

POST /v2/image/generate

Request Body

{
  "success": true,
  "images": [{ "url": "https://...", "revised_prompt": "..." }],
  "model": "dall-e-3",
  "api_cost": 0.08
}

POST /v2/video/generate

Request Body

{
  "success": true,
  "task_id": "task_video_a1b2c3d4e5f6",
  "status": "processing",
  "model": "veo-3.1-generate-preview",
  "estimated_time_seconds": 120,
  "message": "Video generation started. Poll GET /v2/tasks/{task_id}"
}

POST /v2/music/generate

Request Body

{
  "success": true,
  "task_id": "task_music_a1b2c3d4e5f6",
  "suno_task_id": "suno_abc123",
  "status": "processing",
  "model": "suno-v3.5",
  "estimated_time_seconds": 60
}

GET /v2/tasks/{taskId}

{
  "task_id": "task_video_a1b2c3d4e5f6",
  "type": "video",
  "status": "processing",
  "created_at": "2026-03-02T04:30:00Z"
}

{
  "task_id": "task_video_a1b2c3d4e5f6",
  "type": "video",
  "status": "completed",
  "result_url": "https://storage.googleapis.com/.../video.mp4"
}

{
  "task_id": "task_video_a1b2c3d4e5f6",
  "type": "video",
  "status": "failed",
  "error": "Content filtered by safety system",
  "filter_reasons": ["Violence detected"]
}

Task statuses: pending → processing → completed / failed

GET /v2/models

Smart Routing

The API automatically selects the optimal model based on task complexity, language, and content. Override with force_model when needed.

Error Codes

Rate Limits

Rate limits are applied per API key. Current limits:

When rate limited, you'll receive a 429 Too Many Requests response. Wait and retry.