Developer API Overview

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"}'

The key is in the fullKey field of the response (HTTP 201). Besides the required name, the body accepts permissions (array, optional, values read and write only — default ["read","write"]; anything else is a 400) and expiresInDays (number, optional, default 365, clamped to 1–730). You may hold at most 50 active keys; creating the 51st returns a 400. If you lose the key you can re-reveal it with GET /api/api-keys/:keyId/reveal (same JWT auth, rate limited) or from the Developer Console.

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",
  "model": "auto",
  "credits_charged": 12,
  "poll_url": "/v1/generate/abc123/status",
  "poll_interval_hint": 3,
  "session_id": "68f...",
  "project_id": "68e..."
}

model echoes back what the server resolved your request to. Omitting model echoes "auto" on every Smart-Select-routed type (image, image edit, video, video-from-image, elements, first-last-frame, lipsync, video-to-video, chat, transcription, 3D). POST /v1/generate/music, /v1/generate/speech, and /v1/generate/sound instead substitute a concrete default identifier for that type and echo it; POST /v1/edit/image and POST /v1/edit/video echo null. poll_interval_hint is seconds: 2 for chat, 3 for image and image-edit, 5 for sound and Creative Director, 8 for everything else. session_id and project_id tell you where the generation landed in the app (project_id is the auto-created "API Generations" project when you did not pass one).

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",
  "type": "image",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": ["https://cdn.kolbo.ai/..."],
    "thumbnail_url": "https://cdn.kolbo.ai/...",
    "model": "nano-banana-2",
    "prompt_used": "A breathtaking sunset...",
    "created_at": "2026-07-27T09:14:02.913Z"
  },
  "credits_used": 12,
  "credits_breakdown": [
    { "model": "nano-banana-2", "amount": 12, "base": 10, "final": 12 }
  ]
}

4. Detecting Success

const started = await res.json();
if (!res.ok || started.success === false || started.status === false) {
  throw new Error(started.error ?? started.message ?? `HTTP ${res.status}`);
}

5. Using the Output URL

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);
    // `cancelled` carries neither `result` nor `error`. Without this branch the
    // loop polls a cancelled generation forever.
    if (status.state === "cancelled") throw new Error("Generation was cancelled");
  }
}

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"])
        # `cancelled` carries neither `result` nor `error`. Without this branch the
        # loop polls a cancelled generation forever.
        if status["state"] == "cancelled":
            raise Exception("Generation was cancelled")

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

Generation Types

Every endpoint below returns immediately with a generation_id (POST /v1/chat calls the same handle message_id) and is polled at GET /v1/generate/:generation_id/status. Video Trim is the one exception — it runs on its own job collection and is not resolvable on the generic status route. It returns no poll_url: Video Trim replies 202 with jobId (poll GET /v1/video/trim/:jobId — ignore the pollingUrl it also returns, which points at the in-app route). Creative Director is resolvable on it (the generic route detects the batch and internally delegates to the per-scene endpoint), but the dedicated GET /v1/generate/creative-director/:id/status path returns the same payload with one less hop. See Polling & Cancellation.

Visual DNA

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

See Visual DNA for details.

Moodboards

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

Create, update, and delete moodboards with POST /v1/moodboards, PUT /v1/moodboards/:id, and DELETE /v1/moodboards/:id. Pass moodboard_id to image generation, image editing, or Creative Director requests. See Moodboards for details.

Color DNA

A saved color palette that becomes one project's grade. A project stores at most one palette (castColorPaletteId), and while it is set, generations that run inside that project are color-graded automatically. There is no account-wide palette — a generation with no resolved project gets no grade.

See Color Palettes for details.

Cinematic Presets

Pass the ids you want in the optional cinematic object on POST /v1/generate/image and POST /v1/generate/image-edit. See Cinematic Presets.

Music Library

Search Kolbo's catalog of licensed, ready-made background tracks (distinct from music generation). Discovery is free; the two acquisition endpoints are paid.

See Music Library for details.

Stock Library

Unified, multi-source stock media — photos, videos, illustrations, vectors, 3D models, sound effects, and music. Find b-roll, references, and project assets. All endpoints are free (no credits).

Sources reachable from the API: kolbo-ai (Kolbo's own AI sound effects, music, and images), pexels, unsplash, pixabay, coverr, freesound, sketchfab. Call GET /v1/stock/sources for the live list and each source's supported media types and filters.

See Stock Library for details, and Asset Library License & Terms of Use for the license governing anything you import.

Chat

Send messages to any Kolbo chat model with multi-turn conversation support. Call GET /v1/models?type=chat for the current list of chat model identifiers.

See Chat for details.

Media Library

Upload local files to the user's Kolbo library, get back a stable CDN URL, and browse everything the user has — uploaded files and AI-generated outputs — with the same filters as the desktop app and Adobe plugin (by project, folder, type, and section).

See Media Library for the full filter reference and examples.

Presets Discovery

Projects

Every generation endpoint accepts an optional project_id body field that routes the generation into a specific project. See Projects.

Custom Chat Agents

Reusable named personas for chat. The agent's description is the system instruction the model adopts.

See Agents & Sessions for details.

Voices

Video Trim

See Video Editing and Trim for details.

HTML Artifacts

Publish a self-contained HTML page, SVG, or Mermaid document to a public URL.

Other Endpoints

Reference

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.