Elements Generation

Generate animated videos from reference images and text prompts. Elements combines your reference assets with AI animation to produce dynamic video content.

Smart Select (recommended): Omit the model field and Kolbo automatically picks the best model for your prompt. This is the default and recommended approach for most use cases.

Model identifiers are Kolbo-specific. Never hardcode model identifiers — always fetch the current list from GET /api/v1/models?type=elements first. Models may be added, renamed, or retired at any time.

Endpoint

POST /api/v1/generate/elements

Request Body

Accepts application/json or multipart/form-data (when uploading files).

Field	Type	Required	Description
`prompt`	string	Yes	Text description of the animation
`model`	string	No	Model identifier from `GET /api/v1/models?type=elements` (default: auto-select)
`reference_images`	array	No	URLs of reference images for the animation
`files`	multipart	No	Reference media files (max 200 MB total)
`duration`	number	No	Duration in seconds (default: `5`)
`aspect_ratio`	string	No	`"16:9"`, `"9:16"`, `"1:1"` (default: `"16:9"`)
`motion`	string	No	Motion style for the animation
`preset_id`	string	No	Preset ID from `GET /api/v1/presets?type=elements`
`enhance_prompt`	boolean	No	Enhance prompt (default: `true`)
`visual_dna_ids`	array	No	Visual DNA IDs for character/product consistency (max 3)

Examples

cURL (Smart Select — recommended):

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 glowing crystal slowly rotating with particles floating around it",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

cURL with reference images:

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 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 "duration=5" \
  -F "aspect_ratio=16:9"

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: "A glowing crystal slowly rotating with particles floating around it",
      duration: 5,
      aspect_ratio: "16:9"
    })
  });

  const data = await response.json();
  console.log("Generation ID:", data.generation_id);
  console.log("Poll URL:", data.poll_url);

  // Poll for completion
  const pollForResult = async (generationId) => {
    while (true) {
      await new Promise((r) => setTimeout(r, data.poll_interval_hint * 1000));
      const status = await fetch(
        `https://api.kolbo.ai/api/v1/generate/${generationId}/status`,
        { headers: { "X-API-Key": API_KEY } }
      ).then((r) => r.json());

      console.log("State:", status.state, "Progress:", status.progress);

      if (status.state === "completed") {
        console.log("Video URL:", status.result.urls[0]);
        return status;
      }
      if (status.state === "failed") {
        console.error("Generation failed:", status.error);
        return status;
      }
    }
  };

  await pollForResult(data.generation_id);
}

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": "A glowing crystal slowly rotating with particles floating around it",
        "duration": 5,
        "aspect_ratio": "16:9",
    },
)

data = response.json()
print("Generation ID:", data["generation_id"])
print("Poll URL:", data["poll_url"])

# Poll for completion
generation_id = data["generation_id"]
poll_interval = data.get("poll_interval_hint", 8)

while True:
    time.sleep(poll_interval)
    status = requests.get(
        f"https://api.kolbo.ai/api/v1/generate/{generation_id}/status",
        headers={"X-API-Key": API_KEY},
    ).json()

    print(f"State: {status['state']}  Progress: {status.get('progress', 0)}%")

    if status["state"] == "completed":
        print("Video URL:", status["result"]["urls"][0])
        break
    if status["state"] == "failed":
        print("Error:", status.get("error"))
        break

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": "A glowing crystal slowly rotating with particles floating around it",
    "model": "MODEL_IDENTIFIER_FROM_MODELS_ENDPOINT",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Model identifiers come from GET /api/v1/models?type=elements. Always fetch the latest list rather than hardcoding identifiers, as models may change over time.

Response

Initial Response

{
  "success": true,
  "generation_id": "elem123",
  "type": "elements",
  "model": "auto",
  "credits_charged": 50,
  "poll_url": "/api/v1/generate/elem123/status",
  "poll_interval_hint": 8
}

Completed Status

{
  "success": true,
  "generation_id": "elem123",
  "type": "elements",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": ["https://cdn.kolbo.ai/videos/..."],
    "thumbnail_url": "https://cdn.kolbo.ai/thumbs/...",
    "duration": 5,
    "aspect_ratio": "16:9",
    "prompt_used": "A glowing crystal slowly rotating with particles floating around it",
    "model": "auto",
    "created_at": "2026-04-12T10:30:00.000Z"
  }
}

Tips

Use Smart Select (the default). Omit the model field and Kolbo picks the best model for your prompt. This is the simplest and most future-proof approach.
Elements generation typically takes 1-5 minutes depending on the model and duration.
You can provide reference images either as URLs (reference_images) or as file uploads (files). Do not mix both in the same request.
File uploads are limited to 200 MB total per request.
Credits are charged per second: model.credit x duration.
Use poll_interval_hint from the initial response to set your polling interval.
Check supported_durations and supported_aspect_ratios on each model via the Models endpoint before requesting specific values.