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, body { status: true, data: { id, keyPrefix, name, permissions, createdAt, expiresAt }, fullKey, message }). Besides the required name (non-empty string), 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). Key management needs an interactive sign-in: calling these routes with an X-API-Key instead of a JWT returns 403 INTERACTIVE_AUTH_REQUIRED. Key creation is limited to 10 attempts per hour per user. If you lose the key you can re-reveal it with GET /api/api-keys/:keyId/reveal (same JWT auth, 30 requests/minute) 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, chat, 3D); transcription always echoes "auto", and Creative Director echoes the model you sent or "smart_select". Video-to-video has no Smart Select: omitting model there returns 400 MODEL_REQUIRED. POST /v1/generate/music, /v1/generate/speech, and /v1/generate/sound instead substitute a concrete default identifier for that type and echo it (suno-v6, eleven_v4, and elevenlabs-sound-effects-v1 respectively; suno-v5.5 on /v1/generate/music/extend and /cover; music-v1 when the music body carries composition_plan, and on /v1/generate/music/edit-section). POST /v1/edit/image and POST /v1/edit/video echo the engine the edit resolved, falling back to the model you sent, or null.

credits_charged is the up-front estimate (it can be null); the real spend arrives on the status response. poll_interval_hint is seconds: 2 for chat, 3 for /v1/generate/image and /v1/generate/image-edit, 5 for sound and Creative Director, 8 for everything else (including /v1/edit/image). 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 }
  ],
  "session_id": "68f...",
  "project_id": "68e..."
}

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 started = await res.json();
  if (!res.ok || started.success === false || started.status === false) {
    throw new Error(started.error ?? started.message ?? `HTTP ${res.status}`);
  }
  const { generation_id } = started;

  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"}
    )
    started = res.json()
    if not res.ok or started.get("success") is False or started.get("status") is False:
        raise Exception(started.get("error") or started.get("message") or f"HTTP {res.status_code}")
    generation_id = started["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, with two exceptions. Audio Separation runs inline: the request stays open until the stems are ready and the response carries the result, with nothing to poll. Video Trim 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, and the generationId field, which is the same trim job id, not a generation id). 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 (image files sent as multipart are capped at 15 per request, 10 MB each, images only). Pass moodboard_id to image generation, image editing, or Creative Director requests (Creative Director also accepts several as moodboard_ids). See Moodboards for details.

Color DNA

A saved color palette that, once active, color-grades your generations automatically. Color DNA is account-wide: one palette at a time is the account's active palette, and it stays on until you deactivate it or activate another. A project is never required; passing one only records where the palette was born (which shares it with that project's edit/full members) and points the project's showcase at it.

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, keyed by dimension. looks entries are combo recipes, not a dimension you pass: expand a look's bundle ({ <dimension>: <preset id> }) into the cinematic object instead. 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.

Skills (Custom Chat Agents)

Reusable named personas for chat. The skill's description is the system instruction the model adopts. Every route exists under both /v1/skills (current name) and /v1/agents (original path, kept working) with identical behavior.

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.

Personal Fonts

Upload OTF, TTF, or WOFF2 files to your font library, then pass family ids as font_ids on image creation, image editing, or image-mode Creative Director.

See Personal Fonts.

Video Analysis, Video Editor and Downloads

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.