Video Editing and Trim

Two different things live on this page:

• POST /api/v1/edit/video — targeted AI edits of an existing video (upscale, reframe, extend, lipsync, inpaint, and more). Async like every other generation: you get a generation_id and poll /v1/generate/{id}/status.
• POST /api/v1/video/trim — a plain server-side cut by start/end time. Not an AI generation: it runs as its own job with its own polling endpoint.

POST /api/v1/edit/video accepts optional project_id and session_id fields that decide where the result is filed — see Where the edit is filed and Projects. POST /api/v1/video/trim also accepts a project_id field, but the trim job never reads it: it does no project routing, and the trimmed file lands wherever the source lived.

Edit an Existing Video

Endpoint

POST /api/v1/edit/video

Rate limited to 30 requests per minute per account. The bucket is shared with the other SDK generation write routes (video, elements, chat, trim, …), and rejected requests do not count against it. Returns 403 with code INSUFFICIENT_CREDITS (plus balance, required and pricing_url) before any work starts when the account cannot cover the edit.

Choosing a model

Every operation runs on its own pool of models. Pass a concrete identifier from GET /api/v1/models?type=<type> as model, or omit model to use the first model of that pool.

A model that is not in the operation's pool is rejected before any credit is held: 400 with code INVALID_MODEL_FOR_EDIT_TYPE. Identifiers starting with kolbo_gateway_ are web-app navigation aliases, not engines; they are treated as if model were omitted. Model-specific limits, such as the longest source video (max_video_duration), supported resolutions and the extension lengths (min_output_duration/max_output_duration/supported_durations), are listed on each model in that response.

Request Body

video_url and operation are always required. Every other field is read only by the operations listed in its description, and a field sent for the wrong operation is ignored. No field on this route takes an array of reference media: every media input (video_url, image_url, audio_url, mask_video_url) is a single URL.

Where the edit is filed

• With session_id, the edit lands in that session. The session can be any of your text-to-video, image-to-video, video-to-video, lipsync or video-edit sessions, in a project you can edit. project_id is then ignored. A malformed id returns 400 SDK_SESSION_INVALID_ID, and an unknown or deleted session returns 404 SDK_SESSION_NOT_FOUND. A session in a project you cannot see returns 404 SDK_PROJECT_NOT_FOUND, and one in a project where you only have view access returns 403 SDK_PROJECT_ACCESS_DENIED.
• Without session_id, when video_url is exactly the URL of a video you generated on Kolbo (as listed in your media library), the edit joins that video's session. A project_id naming a different project overrides this.
• Otherwise, each edit starts a new API Video Edit - <date> video-to-video session in project_id, or in your auto-created API Generations project when you omit it. A malformed project_id returns 400 SDK_PROJECT_INVALID_ID, an unknown or inaccessible one 404 SDK_PROJECT_NOT_FOUND, and a view-only one 403 SDK_PROJECT_ACCESS_DENIED.

Examples

Reframe a landscape clip to vertical:

curl -X POST https://api.kolbo.ai/api/v1/edit/video \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://cdn.kolbo.ai/videos/source.mp4",
    "operation": "reframe",
    "model": "wan-vace-14b/reframe",
    "aspect_ratio": "9:16",
    "grid_position_x": 0.5,
    "grid_position_y": 0.4
  }'

Add a sound-effects and music bed:

curl -X POST https://api.kolbo.ai/api/v1/edit/video \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://cdn.kolbo.ai/videos/source.mp4",
    "operation": "generate_audio",
    "model": "kling-video/video-to-audio",
    "sound_effect_prompt": "Footsteps on gravel, distant traffic",
    "background_music_prompt": "Sparse ambient pads, slow tempo"
  }'

Lipsync to an audio track:

curl -X POST https://api.kolbo.ai/api/v1/edit/video \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://cdn.kolbo.ai/videos/speaker.mp4",
    "operation": "lipsync",
    "audio_url": "https://cdn.kolbo.ai/audio/voiceover.mp3"
  }'

Poll for the result (JavaScript):

const API_KEY = "kolbo_live_YOUR_API_KEY";

const start = await fetch("https://api.kolbo.ai/api/v1/edit/video", {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    video_url: "https://cdn.kolbo.ai/videos/source.mp4",
    operation: "upscale",
    model: "bytedance-upscaler/upscale/video",
    resolution: "4k",
    target_fps: 60
  })
}).then((r) => r.json());

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

  if (status.state === "completed") {
    console.log("Edited video:", status.result.urls[0]);
    break;
  }
  if (status.state === "failed") {
    console.error(status.error);
    break;
  }
}

Response

Edit started:

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

credits_charged is null when the pipeline has not settled the cost at submit time. The authoritative figure is credits_used on the completed status. model is the concrete engine the server resolved for the edit. When you omit model, it names the default it picked, not null. session_id and project_id say where the edit was filed.

Submit errors use the standard SDK shape { "success": false, "error": "…", "code": "…" } and keep the HTTP status. Besides the field errors in the table above, you may see 400 INVALID_MODEL_FOR_EDIT_TYPE, 400 VIDEO_TOO_LONG, 400 VIDEO_DURATION_UNAVAILABLE (duration-capped models could not read the source length), 400 INVALID_UPSCALE_OPTIONS (a bad Bytedance option combination), 400 UNSUPPORTED_RESOLUTION / INVALID_DURATION / VIDEO_TOO_SHORT (Seedance extend), and 403 INSUFFICIENT_CREDITS or 403 INSUFFICIENT_PERMISSION (no edit permission on the target project). Problems found while the job runs, such as an out-of-range target_fps on Topaz or an over-length extend source, are reported as a failed state on the status endpoint instead.

Completed status:

{
  "success": true,
  "generation_id": "68f2c1a9b4e5d6f7a8b9c0d1",
  "type": "global_video_edit",
  "state": "completed",
  "progress": 100,
  "credits_used": 40,
  "result": {
    "urls": ["https://cdn.kolbo.ai/videos/..."],
    "download_url": "https://cdn.kolbo.ai/videos/...",
    "edit_type": "reframe",
    "duration": 12,
    "model": "the-model-that-actually-ran",
    "created_at": "2026-04-12T10:00:00.000Z"
  }
}

edit_type is the internal name of the operation, which is not always identical to the operation you sent — for example generate_audio reports audio_generation, remove_watermark reports watermark_removal, face_swap reports video_face_swap, and remove_background reports background_removal. result.model is the engine that actually ran.

Finalize a draft

Models that publish draft capabilities in GET /api/v1/models, such as Seedance 2.5 at resolution: "480p-draft", produce a cheap preview that you can later render at full quality. Both draft operations take only video_url (the saved draft, which must be your own generation) and an optional resolution. The server picks the finalization engine itself, so model and prompt are not used.

draft_quote checks the draft and prices the render without starting it or charging anything. It skips the credit gate, does not go through the generation tracker, and returns the quote directly:

{
  "status": true,
  "data": {
    "modelId": "…",
    "modelName": "…",
    "sourceResolution": "480p",
    "resolution": "1080p",
    "supportedResolutions": ["720p", "1080p"],
    "duration": 5,
    "inputSeconds": 0,
    "hasVideoInput": false,
    "credits": 120,
    "expiresAt": "2026-10-06T10:00:00.000Z",
    "previousRenders": []
  }
}

resolution defaults to the first of supportedResolutions. expiresAt is null for drafts that do not expire. previousRenders lists earlier full-quality renders of this draft (generationId, resolution, status, and videoUrl once completed), so you can reuse one instead of paying twice. previousCredits appears only while a price reduction is running. Quote errors use the in-app shape { "status": false, "code": "…", "message": "…" }, with these codes: DRAFT_NOT_FOUND (404), DRAFT_EXPIRED (410), INVALID_DRAFT (400, for example a model that does not support draft rendering), DRAFT_RESOLUTION_UNSUPPORTED, DRAFT_DURATION_UNAVAILABLE and DRAFT_INPUT_DURATION_UNAVAILABLE (400), DRAFT_ENGINE_UNAVAILABLE and DRAFT_PRICING_UNAVAILABLE (503), and DRAFT_QUOTE_FAILED (500) for anything else.

draft_enhance starts the paid render. It returns the normal edit-started response and is polled like any other edit. Each draft renders once per resolution: a second request returns 409 with code DRAFT_RENDER_IN_PROGRESS while the first is still running, or DRAFT_ALREADY_RENDERED afterwards. To make retries safe, send an Idempotency-Key header of 8–128 characters (A-Z, a-z, 0-9, _ . : -); any other value returns 400 INVALID_IDEMPOTENCY_KEY. Replaying the same key for the same draft and resolution returns the original generation_id instead of starting a second render; reusing it for a different draft or resolution returns 409 IDEMPOTENCY_KEY_CONFLICT.

Trim a Video

A frame-accurate server-side cut. This is not an AI generation: it does not go through the generation tracker, it is not pollable via /v1/generate/{id}/status, and no SDK credit gate is applied to it.

Endpoint

POST /api/v1/video/trim
GET  /api/v1/video/trim/{jobId}

The POST is rate limited to 30 requests per minute per account, in the same bucket as the other SDK generation write routes. The status GET is limited to 120 per minute.

Completion contract

Read Polling & Cancellation for the shared concepts — poll intervals, transient-error tolerance, back-off. A trim diverges from that generic contract in almost every field name:

Request Body

Sending start_time or end_time as anything other than a number returns 400 start_time and end_time (seconds, numbers) are required.

Submit Response (202)

{
  "success": true,
  "jobId": "video-trim_1753612345678_k3f9d2p1a",
  "generationId": "video-trim_1753612345678_k3f9d2p1a",
  "status": "processing",
  "message": "Video trim job started",
  "pollingUrl": "/api/video-trim/video-trim_1753612345678_k3f9d2p1a/progress"
}

Status Response

{
  "success": true,
  "jobId": "video-trim_1753612345678_k3f9d2p1a",
  "generationId": "video-trim_1753612345678_k3f9d2p1a",
  "status": "completed",
  "progress": 100,
  "message": "…",
  "error": null,
  "updatedAt": 1753612389421,
  "url": "https://cdn.kolbo.ai/videos/trimmed.mp4",
  "videoUrl": "https://cdn.kolbo.ai/videos/trimmed.mp4",
  "fileUrl": "https://cdn.kolbo.ai/videos/trimmed.mp4",
  "publicUrl": "https://cdn.kolbo.ai/videos/trimmed.mp4"
}

status is normalized to lowercase. The four URL fields carry the same value and appear only once the trimmed file exists — read url. progress climbs 0→100 but is not monotonic across the two execution paths (a heavy clip offloaded to the hosted trimmer reports a different curve than a locally processed one), so drive your logic off status, not progress.

Failure shape

A failed trim is a successful poll — HTTP 200, success: true, with the failure in the payload:

{
  "success": true,
  "jobId": "video-trim_1753612345678_k3f9d2p1a",
  "generationId": "video-trim_1753612345678_k3f9d2p1a",
  "status": "failed",
  "progress": 20,
  "message": "Trimming video...",
  "error": "ffmpeg exited with code 1: …",
  "updatedAt": 1753612389421
}

progress freezes wherever the job died and the URL fields are absent. The error string is the raw failure reason — there is no error code on this route.

Transport-level errors are different: an unknown or expired jobId returns 404 { "success": false, "error": "Trim job not found" }, and a job belonging to another account returns 403 { "success": false, "error": "Access denied to this trim job" }.

Example

# Submit
curl -X POST https://api.kolbo.ai/api/v1/video/trim \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://cdn.kolbo.ai/videos/source.mp4",
    "start_time": 12.5,
    "end_time": 41
  }'

# Poll (jobId from the submit response)
curl https://api.kolbo.ai/api/v1/video/trim/video-trim_1753612345678_k3f9d2p1a \
  -H "X-API-Key: kolbo_live_YOUR_API_KEY"

import requests, time

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

job = requests.post(
    "https://api.kolbo.ai/api/v1/video/trim",
    headers=HEADERS,
    json={
        "video_url": "https://cdn.kolbo.ai/videos/source.mp4",
        "start_time": 12.5,
        "end_time": 41,
    },
).json()

job_id = job["jobId"]

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

    if status["status"] == "completed":
        print("Trimmed video:", status["url"])
        break
    if status["status"] == "failed":
        print("Error:", status.get("error"))
        break

Related