Developer API Overview

Programmatically generate images, videos, music, speech, and sound effects with the Kolbo API.

The Kolbo Developer API lets you programmatically access 100+ AI models for generating images, videos, music, speech, and sound effects. Use it from any language, or integrate directly into Claude Code via our MCP server.

Quick Start

1. Get an API Key

Create a key from the Developer Console or via the API:

curl -X POST https://api.kolbo.ai/api/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App"}'

Save the fullKey from the response -- it is only shown once.

2. Generate an Image

When you omit the model field, Kolbo uses Smart Select to automatically pick the best model for your prompt. This is the recommended approach for most use cases.

curl -X POST https://api.kolbo.ai/api/v1/generate/image \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A sunset over mountains", "aspect_ratio": "16:9"}'

Response:

{
  "success": true,
  "generation_id": "abc123",
  "type": "image",
  "poll_url": "/api/v1/generate/abc123/status",
  "poll_interval_hint": 3
}

3. Poll for Results

Replace abc123 with the generation_id from step 2:

curl https://api.kolbo.ai/api/v1/generate/abc123/status \
  -H "X-API-Key: YOUR_API_KEY"

When complete:

{
  "success": true,
  "generation_id": "abc123",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": ["https://cdn.kolbo.ai/..."],
    "model": "auto",
    "prompt_used": "A breathtaking sunset..."
  }
}

Full Example (JavaScript)

const API_KEY = "YOUR_API_KEY";
const BASE = "https://api.kolbo.ai/api/v1";

async function generateImage(prompt) {
  const res = await fetch(`${BASE}/generate/image`, {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ prompt, aspect_ratio: "16:9" })
  });
  const { generation_id } = await res.json();

  while (true) {
    await new Promise((r) => setTimeout(r, 3000));
    const status = await fetch(`${BASE}/generate/${generation_id}/status`, {
      headers: { "X-API-Key": API_KEY }
    }).then((r) => r.json());

    if (status.state === "completed") return status.result.urls;
    if (status.state === "failed") throw new Error(status.error);
  }
}

generateImage("A sunset over mountains").then(console.log);

Full Example (Python)

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.kolbo.ai/api/v1"

def generate_image(prompt):
    res = requests.post(
        f"{BASE}/generate/image",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json={"prompt": prompt, "aspect_ratio": "16:9"}
    )
    generation_id = res.json()["generation_id"]

    while True:
        time.sleep(3)
        status = requests.get(
            f"{BASE}/generate/{generation_id}/status",
            headers={"X-API-Key": API_KEY}
        ).json()

        if status["state"] == "completed":
            return status["result"]["urls"]
        if status["state"] == "failed":
            raise Exception(status["error"])

urls = generate_image("A sunset over mountains")
print(urls)

Generation Types

Type	Endpoint	Typical Time
Chat	`POST /v1/chat`	2-30s
Image	`POST /v1/generate/image`	10-30s
Image Edit	`POST /v1/generate/image-edit`	10-30s
Video (text)	`POST /v1/generate/video`	1-5 min
Video (from image)	`POST /v1/generate/video/from-image`	1-5 min
Video (from video)	`POST /v1/generate/video-from-video`	2-8 min
Elements (ref → video)	`POST /v1/generate/elements`	2-10 min
First-Last Frame	`POST /v1/generate/first-last-frame`	1-5 min
Lipsync	`POST /v1/generate/lipsync`	1-10 min
Music	`POST /v1/generate/music`	30s-2 min
Speech	`POST /v1/generate/speech`	5-30s
Sound Effects	`POST /v1/generate/sound`	5-30s
Creative Director	`POST /v1/generate/creative-director`	30s-3 min
3D Model	`POST /v1/generate/3d`	2-15 min
Transcription	`POST /v1/transcribe`	30s-5 min

Visual DNA

Create reusable visual identities for characters, products, or styles, then attach them to any generation for consistency.

Endpoint	Description
`POST /v1/visual-dna`	Create a Visual DNA from reference images
`GET /v1/visual-dna`	List your Visual DNAs
`GET /v1/visual-dna/:id`	Get Visual DNA details
`DELETE /v1/visual-dna/:id`	Delete a Visual DNA

See Visual DNA for details.

Moodboards

Discover and apply style templates (moodboards) to guide the visual direction of your generations.

Endpoint	Description
`GET /v1/moodboards`	List available moodboards (personal + presets)
`GET /v1/moodboards/:id`	Get moodboard details

Pass moodboard_id to image generation, image editing, or Creative Director requests. See Moodboards for details.

Chat

Send messages to 20+ AI models with multi-turn conversation support.

Endpoint	Description
`POST /v1/chat`	Send a chat message (requires polling)
`GET /v1/chat/conversations`	List your conversations
`GET /v1/chat/conversations/:id/messages`	Get conversation messages

See Chat for details.

Media Library

Upload local files to the user's Kolbo library and get back a stable CDN URL for reuse across generations.

Endpoint	Description
`POST /v1/media/upload`	Upload a file (multipart) and receive a stable URL
`GET /v1/media`	List uploaded media (filter by `type`, `page`, `pageSize`, `searchTerm`)

Presets Discovery

Endpoint	Description
`GET /v1/presets`	List generation presets across image/video/music/text-to-video catalogs (filter with `type`)

Other Endpoints

Endpoint	Description
`GET /v1/models`	List available models
`GET /v1/voices`	List TTS voices
`GET /v1/account/credits`	Check credit balance
`GET /v1/generate/:id/status`	Poll generation status
`GET /v1/generate/creative-director/:id/status`	Poll Creative Director status (per-scene)

Authentication

All requests require the X-API-Key header with your API key:

X-API-Key: YOUR_API_KEY

See Authentication for details on creating and managing keys.

Claude Code Integration

Use Kolbo as native tools in Claude Code via our MCP server. See Claude Code Setup.

On this page