Elements Generation

Generate a video from reference elements — images, videos, and/or an audio track — plus a text prompt. Use it to animate specific assets you already have ("animate this product", "put these three characters into one scene"). For text-only video use Video Generation.

All generation endpoints accept an optional project_id body field that routes the output into a specific project. See Projects.

Endpoint

POST /api/v1/generate/elements

Rate limit: 30 accepted requests per minute per user, counted in a bucket shared with the other standard-limit generation endpoints (/v1/generate/video, /v1/generate/music, /v1/generate/speech, /v1/chat, and so on). Image generation (30/min) and transcription (100/min) have their own buckets. Rejected requests (any 4xx/5xx answer) do not consume the budget.

Request Body

Accepts application/json or multipart/form-data (when uploading files). File uploads and URLs may be combined in the same request.

Provider-asset fields (model-specific)

Some elements models (Gemini Omni family) run against assets that already live with the provider. These optional fields are merged on top of the ids Kolbo derives from visual_dna_ids and passed straight through — leave them unset unless you already hold provider asset ids.

Seedance 2.5 Lipsync (seedance-2-5-lipsync)

This model runs from a prepared performance plan rather than free references. It requires session_id (the Elements session that owns the plan — otherwise 400 PLAN_SESSION_REQUIRED) plus all of performance_plan_id, performance_plan_revision and quote_id (otherwise 400 PLAN_ADMISSION_FIELDS_REQUIRED). Plans are built with the /api/v1/lipsync-plans/{sessionId} routes (below). Sending plan fields with any other model returns 400 PLAN_MODEL_MISMATCH.

Performance plans

A performance plan describes who speaks or sings, which recorded audio drives each character, and the scene. The flow is create → prepare → quote → generate: each step takes the plan's current integer revision, and the quote you receive is what POST /generate/elements admits.

POST  /api/v1/lipsync-plans/:sessionId/assets             (multipart, field "file")
POST  /api/v1/lipsync-plans/:sessionId                    create a plan
GET   /api/v1/lipsync-plans/:sessionId/:planId            read a plan
PATCH /api/v1/lipsync-plans/:sessionId/:planId            replace the plan's fields
POST  /api/v1/lipsync-plans/:sessionId/:planId/prepare    { "revision": 1 }
POST  /api/v1/lipsync-plans/:sessionId/:planId/quote      { "revision": 1 }

:sessionId is an Elements session you can use (the session_id returned by an earlier POST /generate/elements). Reading needs view access to that session; uploading and creating need create access; update, prepare and quote need edit access. These routes answer with { "status": true, "data": { ... } } on success and { "status": false, "code": "...", "message": "..." } on failure. Writes share the 30/min generation limiter; the read uses the 120/min media-library limiter.

Upload an asset. POST .../assets stores an audio, image or video file in your media library for this session and returns 201 with data: { assetId, filename, mediaType, size, url }. Audio and video files may be up to 100 MB, images up to 25 MB (413 MEDIA_FILE_TOO_LARGE); other file types return 415 UNSUPPORTED_MEDIA_TYPE. Any uploaded or generated media-library item you can access in the session's project can also be referenced by its id.

Create or update a plan (manual). The body fields are camelCase:

A dialogue plan needs at least one character and one clip before it can be prepared. Invalid input returns 400 INVALID_LIPSYNC_PLAN with a message naming the problem. PATCH takes the same fields plus the current revision; it replaces the plan, resets it to draft and clears any preparation or quote.

Create a plan (automatic). Send "automatic": true with scenePrompt, attachments (media-library items as [{ "assetId": "...", "name": "optional label" }]: up to 12 audio files, 30 images and 2 videos; at least one audio file is required), optional visualDnaIds (up to 3 character DNAs), performanceMode (dialogue or music_video), durationMs, resolution, aspectRatio and syncPostProcess. Kolbo analyzes the audio and drafts the characters and clips for you. Each audio file must be 30 seconds or shorter, and together they must fit the 30-second scene (AUDIO_EXCEEDS_DURATION).

Prepare and quote. prepare analyzes the selected audio and returns data: { plan, analysis }; it is idempotent for an already prepared revision. quote returns data: { plan, quote } where quote is { quoteId, credits, currency, expiresAt, providerDurationSec, durationMs }. A quote expires after 10 minutes and admits exactly one generation. Only the user who prepared the plan can quote it (403 PLAN_PREPARER_MISMATCH).

Then call POST /api/v1/generate/elements with model: "seedance-2-5-lipsync", the same session_id, performance_plan_id, performance_plan_revision and quote_id.

Examples

cURL with reference images (Smart Select):

curl -X POST https://api.kolbo.ai/api/v1/generate/elements \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Animate the product with a dynamic reveal and floating particles",
    "reference_images": ["https://example.com/product-photo.jpg"],
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

cURL with multiple reference types:

curl -X POST https://api.kolbo.ai/api/v1/generate/elements \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "@Image 1 is the character and @Image 2 is her jacket. She walks through the street from @Video 1, matching its camera move, while @Audio 1 plays as ambience and @Audio 2 as her footsteps.",
    "model": "MODEL_IDENTIFIER_FROM_MODELS_ENDPOINT",
    "reference_images": ["https://example.com/character.jpg", "https://example.com/jacket.jpg"],
    "reference_videos": ["https://example.com/street-plate.mp4"],
    "reference_audio_urls": ["https://example.com/street-ambience.mp3", "https://example.com/footsteps.mp3"],
    "duration": 5,
    "resolution": "1080p"
  }'

Check the chosen model's elements_max_images, elements_max_videos, elements_max_audio and supported_resolutions first — a request over any cap is rejected with 400 REFERENCE_MEDIA_LIMIT_EXCEEDED.

cURL with keyframes (only on models with supports_keyframes: true):

curl -X POST https://api.kolbo.ai/api/v1/generate/elements \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A flower opens from bud to full bloom",
    "model": "MODEL_IDENTIFIER_FROM_MODELS_ENDPOINT",
    "keyframes": [
      { "image_url": "https://example.com/bud.jpg", "timestamp_seconds": 0 },
      { "image_url": "https://example.com/bloom.jpg", "timestamp_seconds": 5 }
    ],
    "duration": 5
  }'

cURL with file upload:

curl -X POST https://api.kolbo.ai/api/v1/generate/elements \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -F "prompt=Animate the product with a dynamic reveal" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "reference_images=https://example.com/logo.png" \
  -F 'reference_videos=["https://example.com/motion-ref.mp4"]' \
  -F "duration=5" \
  -F "aspect_ratio=16:9"

In multipart, repeat files and reference_images once per item; reference_videos, reference_audio_urls, visual_dna_ids and keyframes take a JSON-encoded array string.

JavaScript:

const API_KEY = "kolbo_live_YOUR_API_KEY";

async function main() {
  // Optional: fetch available models
  // const models = await fetch("https://api.kolbo.ai/api/v1/models?type=elements", {
  //   headers: { "X-API-Key": API_KEY }
  // }).then(r => r.json());
  // console.log("Available models:", models);

  const response = await fetch("https://api.kolbo.ai/api/v1/generate/elements", {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      prompt: "Animate the product with a dynamic reveal and floating particles",
      reference_images: ["https://example.com/product-photo.jpg"],
      duration: 5,
      aspect_ratio: "16:9"
    })
  });

  const started = await response.json();
  if (!started.success) throw new Error(started.error);

  const result = await pollUntilDone(started.generation_id, started.poll_interval_hint);
  if (result.state !== "completed") throw new Error(result.error || result.state);

  console.log("Video URL:", result.result.urls[0]); // urls is always an array
}

const TERMINAL = new Set(["completed", "failed", "cancelled"]);

// Minimal loop. A production client should also handle transient HTTP errors and
// an overall timeout — see /docs/developer-api/polling-and-cancellation.
async function pollUntilDone(generationId, intervalSeconds) {
  while (true) {
    await new Promise((r) => setTimeout(r, intervalSeconds * 1000));
    const status = await fetch(
      `https://api.kolbo.ai/api/v1/generate/${generationId}/status`,
      { headers: { "X-API-Key": API_KEY } }
    ).then((r) => r.json());
    if (TERMINAL.has(status.state)) return status;
  }
}

main();

Python:

import requests
import time

API_KEY = "kolbo_live_YOUR_API_KEY"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# Optional: fetch available models
# models = requests.get(
#     "https://api.kolbo.ai/api/v1/models?type=elements",
#     headers={"X-API-Key": API_KEY},
# ).json()
# print("Available models:", models)

response = requests.post(
    "https://api.kolbo.ai/api/v1/generate/elements",
    headers=HEADERS,
    json={
        "prompt": "Animate the product with a dynamic reveal and floating particles",
        "reference_images": ["https://example.com/product-photo.jpg"],
        "duration": 5,
        "aspect_ratio": "16:9",
    },
)

started = response.json()
if not started.get("success"):
    raise Exception(started.get("error"))

TERMINAL = {"completed", "failed", "cancelled"}

# Minimal loop. Add transient-error retries and an overall timeout for production
# — see /docs/developer-api/polling-and-cancellation.
while True:
    time.sleep(started["poll_interval_hint"])
    status = requests.get(
        f"https://api.kolbo.ai/api/v1/generate/{started['generation_id']}/status",
        headers={"X-API-Key": API_KEY},
    ).json()
    if status["state"] in TERMINAL:
        break

if status["state"] != "completed":
    raise Exception(status.get("error", status["state"]))

print("Video URL:", status["result"]["urls"][0])  # urls is always a list

With Specific Model:

First, fetch available models:

curl https://api.kolbo.ai/api/v1/models?type=elements \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY"

Then use a model identifier from the response:

curl -X POST https://api.kolbo.ai/api/v1/generate/elements \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Animate the product with a dynamic reveal and floating particles",
    "reference_images": ["https://example.com/product-photo.jpg"],
    "model": "MODEL_IDENTIFIER_FROM_MODELS_ENDPOINT",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Response

This endpoint is asynchronous and fire-and-forget: the POST answers 202 Accepted as soon as the job is queued and never contains a video.

Generation Started

{
  "success": true,
  "generation_id": "6820f1c2a1b2c3d4e5f60718",
  "type": "elements",
  "model": "auto",
  "credits_charged": null,
  "poll_url": "/v1/generate/6820f1c2a1b2c3d4e5f60718/status",
  "poll_interval_hint": 8,
  "session_id": "6820f1c2a1b2c3d4e5f60700",
  "project_id": "6820f1c2a1b2c3d4e5f606ff"
}

Completed Status

GET /api/v1/generate/{generation_id}/status

{
  "success": true,
  "generation_id": "6820f1c2a1b2c3d4e5f60718",
  "type": "elements",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": ["https://media.kolbo.ai/videos/.../output.mp4"],
    "thumbnail_url": "https://media.kolbo.ai/videos/.../thumb.jpg",
    "duration": 5,
    "aspect_ratio": "16:9",
    "prompt_used": "Animate the product with a dynamic reveal and floating particles",
    "model": "MODEL_IDENTIFIER",
    "created_at": "2026-04-12T10:30:00.000Z"
  },
  "credits_used": 90,
  "credits_breakdown": [
    { "model": "MODEL_IDENTIFIER", "amount": 90, "base": 60, "final": 90, "duration_multiplier": 1.5, "pricing": null }
  ]
}

The output lives in result.urls — always an array of strings, even though this endpoint produces exactly one video. Read urls[0].

result (and credits_used / credits_breakdown) appear only under state: "completed"; a processing body has exactly five keys and no result at all. Every reference asset you sent lands in one finished clip — there is no partial read.

result.thumbnail_url falls back to the first reference image when the pipeline produced no poster frame. result.duration is a number when the pipeline measured it and a string when it falls back to the requested duration — coerce it. result.model is never "auto": it resolves to the identifier that actually ran. The visual_dna, preset and cinematic_presets keys are added only when you sent those inputs. result.reference_images lists the reference URLs the pipeline recorded, when it recorded any, result.model_name carries the display name of the model that ran when the record stores one (typically after Smart Select), and result.playback_urls (one entry per clip, null when the master already plays in every browser) appears when a browser-friendly preview copy exists — urls always stays the master file. credits_used is the authoritative, multiplier-adjusted cost.

Failure and cancellation

A failed generation is still an HTTP 200 with success: true — the failure is in state, with an error string and a best-effort failure object. cancelled carries neither result nor error, so treat all three terminal states explicitly. Failed generations are not charged. See Polling & Cancellation.

Errors

These are returned synchronously by the POST, as { "success": false, "error": "…", "code": "…" } — read limits and offending values from the error message; only INSUFFICIENT_CREDITS and 429 add extra fields. An error without its own code arrives as GENERATION_ERROR.

Errors after the job is accepted

Uploaded files and reference URLs are downloaded and processed after the 202. A problem there does not change the POST answer — the generation ends in state: "failed" with the message in error, and the credit hold is released. Typical causes:

Tips

• Elements generation typically takes 1-5 minutes depending on the model and duration.
• Reference images may be supplied as URLs (reference_images), as multipart files, or as a combination of both — they are merged and counted together.
• URLs are re-routed by extension: a .mp4/.mov/.webm/.avi/.mkv/.m4v URL sent in reference_images is moved to the video slot, and a .mp3/.wav/.aac/.m4a/.flac/.ogg URL is moved to the audio slot. Re-routed URLs then count against that slot's cap.
• There is no cap on the number of uploaded files, but every file counts against its elements_max_* cap and must fit the chosen model's max_file_size (default 50 MB). 200 MB is only the hard transport ceiling.
• Credit cost depends on the model, duration, resolution tier, and whether sound is enabled; models that publish video_input_credit also bill reference-video seconds — see Models and Pricing.
• Use poll_interval_hint from the initial response to set your polling interval.
• Before generating, read elements_max_images, elements_max_videos, elements_max_audio, supported_durations, min_video_duration, max_video_duration, min_audio_duration, max_audio_duration, max_file_size, max_prompt_length, supports_keyframes / max_keyframes, supported_aspect_ratios, and supported_resolutions off the chosen model via GET /api/v1/models?type=elements.

Related