Polling & Cancellation

Every POST /api/v1/generate/* endpoint is asynchronous. It returns immediately with a generation_id and a poll_url, and you read the result from the generic status endpoint below. The same two endpoints work for images, image edits, video, image-to-video, video-to-video, elements, first/last frame, lipsync, music, speech, sound, transcription, 3D and Creative Director — and for chat messages started with POST /api/v1/chat, which is the one endpoint that names its handle message_id instead of generation_id.

How You Learn a Generation Finished

This is by design, not an omission:

An API key can authenticate a Socket.IO connection — that door was opened for an unrelated realtime feature. Do not build on it. The events you would see there are the web app's internal transport: undocumented, unversioned, suppressed for most API-started generations and free to change or disappear without notice. Poll.

What the Start Response Gives You

Every generation endpoint that feeds this contract answers with the same envelope:

Creative Director answers with its own shorter envelope (success, generation_id, type, scene_count, model, poll_url, poll_interval_hint) at HTTP 202, and its poll_url points at the dedicated route. See Creative Director.

Poll Status

Endpoint

GET /api/v1/generate/:generationId/status

No request body. generationId is the generation_id from the start response — a Mongo ObjectId for almost every type, or a gen_... string for POST /api/v1/edit/image. Anything else returns 400 with "Invalid generation ID format".

This route is not covered by the generation rate limiter, so a normal polling loop will not be throttled. Respect the poll_interval_hint (seconds) returned by the start endpoint.

"Not throttled" is per-endpoint, not unlimited: the global safety net of 5,000 requests/minute per API key still counts every poll. A worker watching hundreds of jobs in a tight loop can reach it. Pace by the hint rather than by how fast the endpoint answers. See Global ceiling.

Response Fields

Example

curl https://api.kolbo.ai/api/v1/generate/6612f0a1b2c3d4e5f6a7b8c9/status \
  -H "X-API-Key: kolbo_live_..."

Response (Processing)

{
  "success": true,
  "generation_id": "6612f0a1b2c3d4e5f6a7b8c9",
  "type": "video",
  "state": "processing",
  "progress": 42
}

A processing body has exactly these five keys. There is no result key at all — not an empty one.

Response (Completed)

{
  "success": true,
  "generation_id": "6612f0a1b2c3d4e5f6a7b8c9",
  "type": "video",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": ["https://media.kolbo.ai/videos/..."],
    "thumbnail_url": "https://media.kolbo.ai/videos/...jpg",
    "model": "MODEL_IDENTIFIER",
    "created_at": "2026-07-20T10:11:12.000Z"
  },
  "credits_used": 84,
  "credits_breakdown": [
    {
      "model": "MODEL_IDENTIFIER",
      "amount": 84,
      "base": 42,
      "final": 84,
      "duration_multiplier": 2,
      "pricing": null
    }
  ]
}

Errors

The State Machine

state is a normalised value. Whatever the underlying model or the upstream provider calls a status — queued, initializing, STARTING, UPLOADING, PROCESSING, error, FAILED, streaming, deleted — it is collapsed into one of these before it reaches you. Exactly three raw values map to completed (completed, streaming), failed (error, failed) and cancelled (cancelled, deleted); an unrecognised or missing status falls through to processing.

Where Is My Output URL

result is always attached under state: "completed" and never before. Its shape depends on the generation family. Every URL in it is rewritten onto a Kolbo CDN host before it is returned.

Three things about those URLs, because this is the page that promises them:

• They are plain links. No query string, no signature, no embedded credentials. Fetch them with an ordinary GET, and do not attach X-API-Key — that header belongs to api.kolbo.ai, not to the CDN host.
• No lifetime is published. Nothing guarantees an asset stays reachable at the same address indefinitely, and DELETE /v1/media/:id/permanent removes the underlying file outright. If an asset matters, download the bytes into your own storage instead of persisting the URL as your system of record.
• A lost URL is recoverable without re-generating. GET /v1/media/:id accepts a generation id as well as a media id — see Recovering a lost id.

Images

Applies to POST /v1/generate/image, POST /v1/generate/image-edit and POST /v1/edit/image.

{
  "result": {
    "urls": [
      "https://media.kolbo.ai/kolbo/images/6890...-0.png",
      "https://media.kolbo.ai/kolbo/images/6890...-1.png"
    ],
    "thumbnail_url": "https://media.kolbo.ai/kolbo/images/6890...-0.png",
    "prompt_used": "a neon-lit ramen bar in the rain, shallow depth of field",
    "model": "MODEL_IDENTIFIER",
    "created_at": "2026-07-27T09:14:02.113Z",
    "visual_dna": [{ "id": "688c...", "name": "Maya", "thumbnail_url": "https://media.kolbo.ai/..." }],
    "moodboard": { "id": "6881...", "name": "Q3 Launch" },
    "preset": { "id": "6877...", "name": "Cinematic Portrait" },
    "cinematic_presets": [{ "dimension": "lighting", "name": "Golden Hour" }]
  }
}

Video

Applies to /generate/video, /generate/video/from-image, /generate/elements, /generate/first-last-frame, /generate/video-from-video and /generate/lipsync.

{
  "result": {
    "urls": ["https://media.kolbo.ai/.../output.mp4"],
    "thumbnail_url": "https://media.kolbo.ai/.../thumb.jpg",
    "duration": 5,
    "aspect_ratio": "16:9",
    "prompt_used": "a neon-lit alley in the rain, slow dolly in",
    "model": "MODEL_IDENTIFIER",
    "created_at": "2026-07-27T09:14:02.113Z"
  }
}

Creative-input marks (visual_dna, preset, cinematic_presets) are attached where the endpoint supports them: from-image, elements and first-last-frame can return all three; /generate/video can return preset and cinematic_presets; video-from-video and lipsync return none.

POST /v1/edit/video (global_video_edit) uses a different shape — urls, plus download_url for the production-quality alternate render, edit_type, duration and model. It carries no thumbnail, aspect ratio or prompt. See Video Editing.

Music, Speech and Sound

{
  "result": {
    "urls": [
      "https://media.kolbo.ai/music/.../track-1.mp3",
      "https://media.kolbo.ai/music/.../track-2.mp3"
    ],
    "tracks": [
      { "title": "Neon Rain", "duration": 187.2, "thumbnail_url": null, "model": "MODEL_IDENTIFIER" },
      { "title": "Neon Rain", "duration": 191.0, "thumbnail_url": null, "model": "MODEL_IDENTIFIER" }
    ],
    "title": "Neon Rain",
    "duration": 187.2,
    "lyrics": "[Verse 1]\n...",
    "prompt_used": "dreamy synthwave, analog pads",
    "model": "MODEL_IDENTIFIER",
    "created_at": "2026-07-27T09:12:44.101Z"
  }
}

Transcription

{
  "result": {
    "text": "Welcome back to the show. Today we are talking about ...",
    "srt_url": "https://media.kolbo.ai/stt/.../transcript.srt",
    "txt_url": "https://media.kolbo.ai/stt/.../transcript.txt",
    "word_by_word_srt_url": "https://media.kolbo.ai/stt/.../word-by-word.srt",
    "srt_content": "1\n00:00:00,000 --> 00:00:03,120\nWelcome back to the show.\n\n",
    "duration": 412.5,
    "audio_url": "https://media.kolbo.ai/uploaded-audio/.../episode-42.mp3",
    "model": null,
    "created_at": "2026-07-27T09:31:12.550Z"
  }
}

srt_url, txt_url and word_by_word_srt_url are null when generate_srt was false. srt_content carries the full SRT inline. audio_url is the stored copy of your source file. model is null for transcription, and credits_used / credits_breakdown are not returned for /v1/transcribe — its credit records are not linked to the generation. See Transcription.

3D

{
  "result": {
    "urls": [
      "https://media.kolbo.ai/.../model.glb",
      "https://media.kolbo.ai/.../model.glb",
      "https://media.kolbo.ai/.../model.fbx",
      "https://media.kolbo.ai/.../model.obj",
      "https://media.kolbo.ai/.../model.usdz"
    ],
    "thumbnail_url": "https://media.kolbo.ai/.../preview.png",
    "mode": "single",
    "prompt_used": "a ceramic mug",
    "model": null,
    "created_at": "2026-07-27T10:14:02.113Z"
  }
}

One 3D generation produces every requested format in a single urls array — there is no separate generation per format. The GLB commonly appears twice (once as the primary model URL, once from the format map); de-duplicate client-side. result.model is null for 3D. See 3D Generation.

Chat

A chat turn started with POST /api/v1/chat polls through the same status route, but its result is text-shaped — there is no urls array.

{
  "result": {
    "content": "Quantum computing uses quantum bits (qubits)...",
    "reasoning_content": null,
    "model": "MODEL_IDENTIFIER",
    "created_at": "2026-07-27T09:12:44.101Z"
  }
}

image_urls, video_urls and audio_urls are added only when the turn actually produced media. The status route deliberately holds a chat turn at processing until text or media lands — the message record flips to complete before the streamed tokens are persisted — with a 90-second escape hatch for a genuinely empty reply. See Chat.

Creative Director

Creative Director batches carry a scenes[] array instead of a flat result, and no credits_used / credits_breakdown. Passing a Creative Director generation_id to the generic route transparently delegates to the dedicated route, so both of these return the same body:

GET /api/v1/generate/:generationId/status
GET /api/v1/generate/creative-director/:id/status

See Creative Director for the scene payload.

Failure

A failed generation is a successful poll

The status endpoint returns HTTP 200 with success: true when a generation fails. The failure is in state.

{
  "success": true,
  "generation_id": "6612f0a1b2c3d4e5f6a7b8c9",
  "type": "video",
  "state": "failed",
  "progress": 0,
  "error": "Prompt was rejected by the provider's content policy",
  "failure": {
    "message": "Prompt was rejected by the provider's content policy",
    "category": "content_policy",
    "code": null,
    "retryable": false,
    "severity": null,
    "provider": null
  }
}

Branch on failure.retryable before re-submitting: false means the request needs to change (rephrase the prompt, swap the model); true means a plain retry is safe. null means the cause is unknown — a single retry is reasonable, a retry loop is not.

Synchronous errors on the POST

Rejections that happen before a generation exists come back as a non-2xx on the submit call, in the SDK error envelope. No generation is created and no credits move.

{ "success": false, "error": "prompt is required and must be a non-empty string", "code": "INVALID_PROMPT" }

Full catalogue: Errors & Rate Limits.

A submit that never answered

The dangerous case is earlier than an expired poll window: the POST died at the socket — a reset, a proxy timeout, a crashed worker — and you never learned whether a job was created.

Reconcile before you retry:

1. GET /v1/media?category=ai&sort=created_desc&page_size=5 (add project_id if you sent one) — a job that did start shows up there once it finishes.
2. Or diff GET /v1/account/credits — a reservation for an in-flight generation is already unavailable even though total still counts it.
3. Only submit again once you are satisfied nothing landed.

Full treatment: Retrying a Submit That Never Answered.

Credits on failure

Because there is no charge, a failed poll carries no credits_used and no credits_breakdown — those two fields only ever appear alongside state: "completed". Do not read a missing credits_used as "free"; read it as "not completed, or no credit record linked". The real, multiplier-adjusted cost is always the credits_used on the completed poll — the credits_charged field on the start response is an estimate at best and is null for most families.

Partial Results

Almost nothing streams. For every single-asset family, result is attached only at the terminal completed transition — the output is written in one atomic step, so there is no window in which you can read half of it.

Creative Director scenes

Creative Director is the one family built for incremental consumption. Each scene is persisted the moment it finishes, and the status route exposes image_urls / video_urls for any scene whose status is completed — even while the batch-level state is still processing. Those URLs are final.

The pattern is: poll, consume every scene you have not seen before, keep polling until state is terminal.

Two things to know:

• scenes is [] on the first polls (state: "pending") while the AI plans the batch. That means "not planned yet", not "produced nothing".
• A batch that ends state: "completed" may still contain failed scenes — a batch is marked completed when at least one scene succeeded. Always iterate scenes[] and check each status rather than trusting the batch state.

See Creative Director.

Recommended Polling Pattern

Interval

Use the poll_interval_hint (seconds) from the start response rather than hard-coding one. Its values today:

/v1/edit/image is tracked as global_image_edit, which is not in the 3-second bucket — it hints 8 despite being an image operation.

Overall timeout

A client-side timeout is a display decision, not a failure — the job keeps running on the server and no credits are lost. These are the windows the first-party Kolbo MCP client ships with, tuned against production run times:

For reference, image generation measured over recent production traffic runs p50 ~51s, p90 ~148s, p99 ~277s.

The server runs its own watchdogs. When one fires it marks the generation failed (never cancelled) and releases the credit hold:

Per-model estimates are available up front: GET /api/v1/models returns estimated_duration_seconds for every model. It is not echoed on the status response — there is no ETA field there.

Recovering a lost id

Resuming assumes you still have the handle. If the id is gone — the worker died, the row was never written — do not re-generate. The media library is the recovery path:

See Finding a Generation's Output Again.

Concurrency

Transient errors

A failed status request is not a failed generation. Retry these with backoff instead of aborting the loop:

That list is exactly what the first-party Kolbo MCP client treats as transient. It backs off by interval × 1.5^n, capped at 30 seconds and at 5 doublings, resets the counter on any successful poll, and re-throws only after 30 consecutive failed polls.

if (!res.ok) return { state: "pending" };   // ✗ never do this

JavaScript

const API_KEY = "kolbo_live_...";
const BASE = "https://api.kolbo.ai/api";
const HEADERS = { "X-API-Key": API_KEY, "Content-Type": "application/json" };

const TRANSIENT = new Set([408, 425, 429, 500, 502, 503, 504, 522, 524]);
const TERMINAL = new Set(["completed", "failed", "cancelled"]);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function pollUntilDone(generationId, { interval = 8000, timeout = 900000 } = {}) {
  const url = `${BASE}/v1/generate/${encodeURIComponent(generationId)}/status`;
  const deadline = Date.now() + timeout;
  let transientFailures = 0;

  while (true) {
    if (Date.now() > deadline) {
      // NOT a failure — the job is still running server-side and no credits were lost.
      throw new Error(`Poll window expired for ${generationId}; keep the id and resume polling.`);
    }

    let status;
    try {
      const res = await fetch(url, { headers: HEADERS });
      if (!res.ok) {
        if (!TRANSIENT.has(res.status)) throw new Error(`Poll failed: HTTP ${res.status}`);
        throw Object.assign(new Error(`HTTP ${res.status}`), { transient: true });
      }
      status = await res.json();
      transientFailures = 0;
    } catch (err) {
      const transient = err.transient || err.name === "TypeError";
      if (!transient || ++transientFailures > 30) throw err;
      await sleep(Math.min(interval * Math.pow(1.5, Math.min(transientFailures - 1, 5)), 30000));
      continue;
    }

    if (TERMINAL.has(status.state)) {
      // Music only: an intermediate "completed" at progress 70 carries temporary URLs.
      if (status.type === "music" && status.state === "completed" && status.progress !== 100) {
        await sleep(interval);
        continue;
      }
      if (status.state === "failed") throw new Error(status.error || "Generation failed");
      if (status.state === "cancelled") throw new Error("Generation was cancelled");
      return status;
    }

    await sleep(interval);
  }
}

// Usage
const start = await fetch(`${BASE}/v1/generate/image`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ prompt: "A red sneaker on concrete", model: "MODEL_IDENTIFIER" }),
}).then((r) => r.json());

// `?? start.message_id` is not optional boilerplate: POST /v1/chat is the one
// endpoint that names its handle `message_id`, so a helper that reads only
// `generation_id` polls /v1/generate/undefined/status and gets 400.
const done = await pollUntilDone(start.generation_id ?? start.message_id, {
  interval: (start.poll_interval_hint || 8) * 1000,
  timeout: 120000,
});
console.log(done.result.urls, done.credits_used);

Python

import time
import requests

API_KEY = "kolbo_live_..."  # Replace with your API key
BASE = "https://api.kolbo.ai/api"
HEADERS = {"X-API-Key": API_KEY}

TRANSIENT = {408, 425, 429, 500, 502, 503, 504, 522, 524}
TERMINAL = {"completed", "failed", "cancelled"}


def poll_until_done(generation_id, interval=8.0, timeout=900.0):
    url = f"{BASE}/v1/generate/{generation_id}/status"
    deadline = time.time() + timeout
    transient_failures = 0

    while True:
        if time.time() > deadline:
            # NOT a failure — the job is still running server-side and no credits were lost.
            raise TimeoutError(f"Poll window expired for {generation_id}; keep the id and resume polling.")

        try:
            res = requests.get(url, headers=HEADERS, timeout=30)
            if res.status_code in TRANSIENT:
                raise requests.RequestException(f"HTTP {res.status_code}")
            res.raise_for_status()
            status = res.json()
            transient_failures = 0
        except requests.RequestException:
            transient_failures += 1
            if transient_failures > 30:
                raise
            time.sleep(min(interval * (1.5 ** min(transient_failures - 1, 5)), 30))
            continue

        if status["state"] in TERMINAL:
            # Music only: an intermediate "completed" at progress 70 carries temporary URLs.
            if status["type"] == "music" and status["state"] == "completed" and status.get("progress") != 100:
                time.sleep(interval)
                continue
            if status["state"] == "failed":
                raise RuntimeError(status.get("error", "Generation failed"))
            if status["state"] == "cancelled":
                raise RuntimeError("Generation was cancelled")
            return status

        time.sleep(interval)


start = requests.post(
    f"{BASE}/v1/generate/image",
    headers=HEADERS,
    json={"prompt": "A red sneaker on concrete", "model": "MODEL_IDENTIFIER"},
).json()

# `or start.get("message_id")` is not optional boilerplate: POST /v1/chat is the
# one endpoint that names its handle `message_id`, so a helper that reads only
# `generation_id` polls /v1/generate/None/status and gets 400.
job_id = start.get("generation_id") or start.get("message_id")
done = poll_until_done(job_id, interval=start.get("poll_interval_hint", 8), timeout=120)
print(done["result"]["urls"], done.get("credits_used"))

Cancel

Stops a running generation and releases or refunds its credits. This is the same code path the Kolbo web app uses, so provider aborts and refunds behave identically whichever surface cancelled.

Endpoint

POST /api/v1/generate/:generationId/cancel

No request body. Rate limited with the shared generation limiter (10 requests/minute in production, keyed by account rather than by individual API key).

Example

curl -X POST https://api.kolbo.ai/api/v1/generate/6612f0a1b2c3d4e5f6a7b8c9/cancel \
  -H "X-API-Key: kolbo_live_..."

Response (Cancelled)

{
  "success": true,
  "generation_id": "6612f0a1b2c3d4e5f6a7b8c9",
  "type": "video",
  "state": "cancelled",
  "credits_refunded": 84
}

For a Creative Director batch the response also carries batch_cancelled_count — the number of in-flight scenes that were stopped along with the batch. A Creative Director cancel refunds only the scenes that had not finished; completed scenes stay charged, and a batch where some scenes already succeeded is finalised as completed rather than cancelled.

Response Fields

Errors

Only generations in a live state can be cancelled (processing, queued, pending, initializing, starting, generating). Anything else returns 409.

What cannot be cancelled

Flows That Do Not Use This Route

One flow is job-based rather than generation-based. It has its own poll route and its own state vocabulary, and passing its id to GET /api/v1/generate/{id}/status returns 404 Generation not found.

It does not return poll_interval_hint — the Interval section above applies only to the generic status route. Build the poll URL yourself and pick an interval from the column above.

The rule at the top still holds for all three: they poll too. There is no push mechanism anywhere in the API.

Related