Video-to-Video

Restyle and transform existing videos using AI. Provide a source video and a text prompt describing the desired transformation, and Kolbo generates a new video with the applied style or changes.

All generation endpoints accept an optional project_id body field that routes the output into a specific project. See Projects. Rate limit: 30 accepted requests per minute per user (all API keys on one account share the counter), counted in one bucket shared with the other standard-limit /v1/generate/* routes; requests that fail are not counted. The endpoint returns 403 / INSUFFICIENT_CREDITS before any work starts when the account cannot cover the generation.

Endpoint

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

Request Body

Accepts multipart/form-data (for file uploads) or application/json (for URL-based inputs).

Motion Control (character image + driving video)

Motion-control models transfer the motion of a reference video onto a character image. They are matched by identifier: anything containing motion-control (such as the Kling v2.6 / v3 motion-control models), animate-move / animate/move (including wan/v2.2-14b/animate/move), wan-animate or dreamactor (including bytedance/dreamactor/v2), plus act_two. For these models the inputs are:

• reference_images[0] — the character image (the subject that gets animated). Must be a Kolbo-hosted URL whose path has an image extension (.jpg, .jpeg, .png, .gif, .bmp, .webp, .tiff), otherwise 400 with INVALID_VIDEO_SOURCE or INVALID_CHARACTER_IMAGE_TYPE.
• video_url — the driving / reference video whose motion is transferred (in the MCP tool this is the source_video argument). Its path must have a video extension (.mp4, .mov, .avi, .mkv, .webm, .m4v, .flv, .wmv), otherwise 400 / INVALID_REFERENCE_VIDEO_TYPE.

Omitting the character image, or sending the driving video as an uploaded files part instead of video_url, returns 400 with code MOTION_CONTROL_INPUTS before any credits are held. Send both as URLs (upload a local file to the Media Library first). The cost is sized from the driving video's length.

curl -X POST https://api.kolbo.ai/api/v1/generate/video-from-video \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-motion-control-model-identifier",
    "reference_images": ["https://media.kolbo.ai/images/character.jpg"],
    "video_url": "https://media.kolbo.ai/videos/dance-reference.mp4"
  }'

VEED Subtitles (prompt-less)

The VEED Subtitles model (veed/subtitles) burns styled, auto-transcribed subtitles into a video. It takes no prompt — pass a style preset and optional language settings instead. Billed per minute of input video with a 1-minute minimum.

curl -X POST https://api.kolbo.ai/api/v1/generate/video-from-video \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veed/subtitles",
    "video_url": "https://media.kolbo.ai/videos/talking-clip.mp4",
    "preset": "glass",
    "source_language": "en-US",
    "translation_language": "es-ES"
  }'

Input limits

There is no generic server-side check of max_images, max_videos, max_elements or the source-length fields on the model record. A few families validate their own inputs before any charge:

• Seedance (seedance-2…): the source must be Kolbo-hosted and at least the model's min_video_duration long (400 / VIDEO_TOO_SHORT); the edit models take one model per request.
• Wan 3.0 (wan3.0-video-to-video, wan3.0-prime-video-to-video): a source above max_video_duration returns 400 / VIDEO_TOO_LONG; a duration above the longest supported_durations entry returns 400 / DURATION_NOT_SUPPORTED.
• FLUX 3 Edit Video (flux-3-edit-video): sources of 15 s or longer return 400 / VIDEO_TOO_LONG.
• Pruna P-Video (prunaai/p-video-*): source length and reference-image count are checked (VIDEO_TOO_LONG, MISSING_REFERENCE_IMAGE, TOO_MANY_REFERENCE_IMAGES).
• Morphious / Genjutsu: exactly one source video plus a mode-specific reference-image range, duration and resolution (400 / INVALID_MORPHIOUS_INPUT or INVALID_GENJUTSU_INPUT).

For every other model, validate against the model record yourself — over-sending fails at the provider mid-generation instead of returning a clean 400.

Billing

Most models are billed per second of the probed source video (motion-control models: the driving video), not the duration you request. Exceptions: Seedance edit and extend models add their extra input / requested output seconds on top of the source; VEED Subtitles bills a 60-second minimum; Luma Ray 3.2 bills the selected 5 s or 10 s output tier; Topaz Slow Motion bills the slowed-down output length; Runway Aleph 2.0 bills at least 2 seconds. Read the settled cost from credits_used on the completed status.

Examples

cURL with URL

First fetch identifiers from GET /api/v1/models?type=video_from_video, then pass the identifier value as model. The source video must already be on Kolbo storage:

curl -X POST https://api.kolbo.ai/api/v1/generate/video-from-video \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-identifier",
    "prompt": "Transform into anime style with vibrant colors",
    "video_url": "https://media.kolbo.ai/videos/original-clip.mp4",
    "aspect_ratio": "16:9"
  }'

cURL with File Upload

curl -X POST https://api.kolbo.ai/api/v1/generate/video-from-video \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -F "model=your-model-identifier" \
  -F "prompt=Transform into anime style with vibrant colors" \
  -F "[email protected]"

Timestamp-Anchored Keyframes

Models that support keyframes let you pin specific images to specific moments in the output. The keyframe images must already live on Kolbo storage — upload them through the Media Library first.

curl -X POST https://api.kolbo.ai/api/v1/generate/video-from-video \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-keyframe-capable-model-identifier",
    "video_url": "https://media.kolbo.ai/videos/source.mp4",
    "prompt": "Match the reference frames",
    "source_fps": 24,
    "source_duration_seconds": 8,
    "keyframes": [
      { "image_url": "https://media.kolbo.ai/images/frame-a.png", "timestamp_seconds": 0 },
      { "image_url": "https://media.kolbo.ai/images/frame-b.png", "timestamp_seconds": 4.5 }
    ]
  }'

JavaScript

const API_KEY = "kolbo_live_YOUR_API_KEY";

// Fetch available video-to-video models
async function initModels() {
  const res = await fetch("https://api.kolbo.ai/api/v1/models?type=video_from_video", {
    headers: { "X-API-Key": API_KEY },
  });
  const data = await res.json();
  console.log("Available models:", data.models.map((m) => m.identifier));
}

async function main() {
  await initModels();

  const response = await fetch("https://api.kolbo.ai/api/v1/generate/video-from-video", {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "your-model-identifier", // required — no auto-select on this endpoint
      prompt: "Transform into anime style with vibrant colors",
      video_url: "https://media.kolbo.ai/videos/original-clip.mp4",
      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"
BASE_URL = "https://api.kolbo.ai/api"
HEADERS = {"X-API-Key": API_KEY}

# Fetch available video-to-video models
models_res = requests.get(
    f"{BASE_URL}/v1/models",
    headers=HEADERS,
    params={"type": "video_from_video"},
)
print("Available models:", [m["identifier"] for m in models_res.json()["models"]])

# --- Option A: Using URL ---
response = requests.post(
    f"{BASE_URL}/v1/generate/video-from-video",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "model": "your-model-identifier",  # required — no auto-select on this endpoint
        "prompt": "Transform into anime style with vibrant colors",
        "video_url": "https://media.kolbo.ai/videos/original-clip.mp4",
        "aspect_ratio": "16:9",
    },
)

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

# --- Option B: Using file upload ---
# with open("original-clip.mp4", "rb") as vid:
#     response = requests.post(
#         f"{BASE_URL}/v1/generate/video-from-video",
#         headers=HEADERS,
#         files={"files": vid},
#         data={
#             "model": "your-model-identifier",
#             "prompt": "Transform into anime style with vibrant colors",
#         },
#     )
#     data = response.json()

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(data["poll_interval_hint"])
    status = requests.get(
        f"{BASE_URL}/v1/generate/{data['generation_id']}/status",
        headers=HEADERS,
    ).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

Response

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

Generation Started

{
  "success": true,
  "generation_id": "68f2c1a9b4e5d6f7a8b9c0d1",
  "type": "video_from_video",
  "model": "your-model-identifier",
  "credits_charged": null,
  "poll_url": "/v1/generate/68f2c1a9b4e5d6f7a8b9c0d1/status",
  "poll_interval_hint": 8,
  "session_id": "…",
  "project_id": "…"
}

Completed Status

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

{
  "success": true,
  "generation_id": "68f2c1a9b4e5d6f7a8b9c0d1",
  "type": "video_from_video",
  "state": "completed",
  "progress": 100,
  "result": {
    "urls": ["https://media.kolbo.ai/videos/.../output.mp4"],
    "thumbnail_url": null,
    "duration": 5,
    "aspect_ratio": "16:9",
    "prompt_used": "Transform into anime style with vibrant colors",
    "model": "your-model-identifier",
    "created_at": "2026-04-12T10:00:00.000Z"
  },
  "credits_used": 50,
  "credits_breakdown": [
    { "model": "your-model-identifier", "amount": 50, "base": 50, "final": 50, "duration_multiplier": null, "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. There is no partial or streaming read.

result.thumbnail_url is usually null here — video-to-video has no source still to fall back on, so it is populated only when the pipeline generated a poster frame. result.duration is the recorded output length when the pipeline stored one; otherwise it falls back to the duration you sent (stored as a string) or null.

Optional result keys, present only when they have data: model_name (display name of the model that ran), playback_urls (browser-playable companions to urls, null per clip when the master already plays everywhere), reference_images (the references the generation actually conditioned on, including injected Visual DNA stills), visual_dna ([{ id, name, thumbnail_url }] for the DNAs used) and style ({ id, name, cover, custom } for a Morphious style).

credits_used is the authoritative, multiplier-adjusted cost, not credits_charged from the submit response.

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.

Tips

• Pick the model first. max_images, max_videos, max_elements, min_video_duration, and max_video_duration on the model record describe which extra inputs the model takes and what source length it is built for. Only some families enforce them (see Input limits), so validate against the model record yourself before submitting.
• Upload source videos, character images and keyframe images to the Media Library first and pass the returned URLs — an external video_url, motion-control character image or keyframe image is rejected.
• Video-to-video generation typically takes several minutes depending on the model and duration.
• Be descriptive in your prompt — specify the target style, mood, and any visual changes you want applied.
• When using file uploads, the limit is 100 MB per file.
• Read the settled cost from credits_used on the completed status response — see Credits and Billing.
• 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.

Related