Video Generation

Generate videos from text or animate images using models like Kling, Seedance, Hailuo, Sora, and more.

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=video first. Models may be added, renamed, or retired at any time.

Text to Video

Endpoint

POST /api/v1/generate/video

Request Body

Field	Type	Required	Description
`prompt`	string	Yes	Text description of the video
`model`	string	No	Model identifier from `GET /api/v1/models?type=video` (default: auto-select)
`aspect_ratio`	string	No	`"16:9"`, `"9:16"`, `"1:1"` (default: `"16:9"`)
`duration`	number	No	Duration in seconds, e.g. `5` or `10` (default: `5`)
`enhance_prompt`	boolean	No	Enhance prompt (default: `true`)
`visual_dna_ids`	array	No	Visual DNA IDs for character/product consistency (max 3)
`reference_images`	array	No	URLs of reference images for style/content guidance

Examples

cURL (Smart Select — recommended):

curl -X POST https://api.kolbo.ai/api/v1/generate/video \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A drone flying over a snowy mountain range at golden hour",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

JavaScript:

const API_KEY = "kolbo_live_YOUR_API_KEY";

async function main() {
  const response = await fetch("https://api.kolbo.ai/api/v1/generate/video", {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      prompt: "A drone flying over a snowy mountain range at golden hour",
      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"}

response = requests.post(
    "https://api.kolbo.ai/api/v1/generate/video",
    headers=HEADERS,
    json={
        "prompt": "A drone flying over a snowy mountain range at golden hour",
        "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 (Kling 3.0 Pro — 18 credits/sec):

curl -X POST https://api.kolbo.ai/api/v1/generate/video \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A drone flying over a snowy mountain range at golden hour",
    "model": "fal-ai/kling-video/v3/pro/text-to-video",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

With Specific Model (Seedance 2.0 — 30 credits/sec):

curl -X POST https://api.kolbo.ai/api/v1/generate/video \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A drone flying over a snowy mountain range at golden hour",
    "model": "seedance-2-text-to-video",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

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

Image to Video

Animate a still image into a video.

Endpoint

POST /api/v1/generate/video/from-image

Request Body

Field	Type	Required	Description
`image_url`	string	Yes	URL of the source image
`prompt`	string	No	Motion/animation description
`model`	string	No	Model identifier from `GET /api/v1/models?type=video_from_image` (default: auto-select)
`aspect_ratio`	string	No	`"16:9"`, `"9:16"`, `"1:1"` (default: `"16:9"`)
`duration`	number	No	Duration in seconds (default: `5`)
`enhance_prompt`	boolean	No	Enhance prompt (default: `true`)
`visual_dna_ids`	array	No	Visual DNA IDs for consistency (max 3)

Examples

cURL (Smart Select — recommended):

curl -X POST https://api.kolbo.ai/api/v1/generate/video/from-image \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "prompt": "Slow zoom in with gentle camera pan",
    "duration": 5
  }'

JavaScript:

const API_KEY = "kolbo_live_YOUR_API_KEY";

async function main() {
  const response = await fetch("https://api.kolbo.ai/api/v1/generate/video/from-image", {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      image_url: "https://example.com/photo.jpg",
      prompt: "Slow zoom in with gentle camera pan",
      duration: 5
    })
  });

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

  // Poll for completion (same pattern as text-to-video above)
  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"}

response = requests.post(
    "https://api.kolbo.ai/api/v1/generate/video/from-image",
    headers=HEADERS,
    json={
        "image_url": "https://example.com/photo.jpg",
        "prompt": "Slow zoom in with gentle camera pan",
        "duration": 5,
    },
)

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

# 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 (Kling 3.0 Pro — 18 credits/sec):

curl -X POST https://api.kolbo.ai/api/v1/generate/video/from-image \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "prompt": "Slow zoom in with gentle camera pan",
    "model": "fal-ai/kling-video/v3/pro/image-to-video",
    "duration": 5
  }'

With Specific Model (Seedance 2.0 — 30 credits/sec):

curl -X POST https://api.kolbo.ai/api/v1/generate/video/from-image \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "prompt": "Slow zoom in with gentle camera pan",
    "model": "seedance-2-img-to-video",
    "duration": 5
  }'

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

Response

Both endpoints return the same format:

{
  "success": true,
  "generation_id": "vid123",
  "type": "video",
  "model": "auto",
  "credits_charged": 35,
  "poll_url": "/api/v1/generate/vid123/status",
  "poll_interval_hint": 8
}

Completed Status

{
  "success": true,
  "generation_id": "vid123",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": ["https://cdn.kolbo.ai/videos/..."],
    "thumbnail_url": "https://cdn.kolbo.ai/thumbs/...",
    "duration": 5,
    "aspect_ratio": "16:9",
    "model": "auto"
  }
}

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.
Video generation takes 1-5 minutes depending on the model and duration.
Check supported_durations and supported_aspect_ratios on each model via the Models endpoint before requesting specific values.
Credits are charged per second: model.credit x duration.
Use poll_interval_hint from the initial response to set your polling interval.
Not all models support all durations or aspect ratios — if unsupported, the API may select the closest match.

On this page