Video Editor API

All endpoints require API-key authentication. Reads require project view access; writes (create, update, export) require current project edit access and a write-enabled key. Timeline times use milliseconds. Media URLs must be HTTPS files on Kolbo's own storage with a supported extension (mp4, mov, webm, m4v, mp3, wav, m4a, aac, ogg, flac, png, jpg, jpeg, webp, gif); import external media into the media library first.

Request bodies and query strings are validated strictly: unknown top-level fields, and unknown fields inside session_data, session_flags and operations, are rejected with 400 INVALID_INPUT. Unknown keys inside clips[], audio[] and texts[] entries are ignored.

Creating and editing timelines costs no credits.

Create a timeline

POST /api/v1/editor/sessions

{
  "project_id": "YOUR_PROJECT_ID",
  "name": "Campaign edit",
  "format": "16:9",
  "clips": [
    {"url": "YOUR_KOLBO_IMAGE_URL", "duration_ms": 2000},
    {"url": "YOUR_KOLBO_VIDEO_URL", "trim_start_ms": 500}
  ],
  "audio": [{"url": "YOUR_KOLBO_MUSIC_URL", "volume": 0.35, "fade_out_ms": 1000}],
  "texts": [{"content": "ORBIT", "start_ms": 0, "duration_ms": 2000, "vertical": "bottom"}]
}

Each clips[] entry:

Each audio[] entry:

Each texts[] entry:

Every item has a minimum duration of 200 ms, and the clip timeline is limited to 30 minutes. Media inspection is bounded to 128 MB per file, 256 MB and two minutes per request.

The response is {success: true, data: {session_id, editor_url, duration_ms, format, tracks, notes}}. editor_url is an app-relative path (/video-tools?tool=video-editor&session=...) on the Kolbo web app; tracks is a list of summaries such as "Video: 2 item(s)". Retain the returned session ID; creation is not a polling operation.

Advanced creation accepts session_data (the same object as the update endpoint below) instead of clips/audio/texts, including blank or caption-only timelines.

Export or check an export

POST /api/v1/editor/exports

{"session_id": "SAVED_SESSION_ID", "quality": "720p"}

The request waits up to about 60 seconds. Completed data contains video_url, duration_ms, file_name and job_id. A pending result contains pending: true, status, job_id and message; repeat with that same session_id and job_id to check it. Do not recreate the timeline or resubmit generation.

Identical snapshots (same session data and quality) reuse their export job. A failed or cancelled export returns an error; to explicitly retry it, omit job_id and set retry_failed: true. A job still queued after 10 minutes is returned as status: "needs_attention"; it is not silently restarted. An account can run at most 3 exports at a time. Exports render up to 60 fps and a 30-minute, 2 MB timeline.

MCP tools: create_video_editor_session and export_video_editor_session, with the same fields. Export saves an MP4 to the media library; it does not publish a website.

Read and edit saved sessions

The list response is {sessions: [{session_id, project_id, name, updated_at, editor_url}], has_more, offset, limit}. The read response contains session_id, project_id, name, revision, editor_url, updated_at, session_flags and the full session_data.

Read the schema and session first. Submit the session's revision with each edit:

{
  "session_id": "SAVED_SESSION_ID",
  "expected_revision": "REVISION_FROM_READ",
  "session_data": { "name": "Campaign final" },
  "operations": [
    { "op": "update_item", "item_id": "CLIP_ID", "patch": { "trimStart": 123.45, "playbackRate": 1.2 } },
    { "op": "reorder_items", "track_id": "TRACK_ID", "item_ids": ["SECOND_CLIP_ID", "CLIP_ID"], "start_time_ms": 0 }
  ]
}

session_id and expected_revision are required, plus at least one of session_data, operations or session_flags. The response contains the updated session summary (including the new revision), duration_ms, item_count and message.

A revision conflict returns HTTP 409 REVISION_CONFLICT. Read again and reapply the intended edit; never blindly retry an old timeline.

Optional session_flags can change isPinned, isArchived or isLocked using the same revision. A locked session rejects edits unless the same request sets isLocked: false.

Operations apply in order and atomically. Audio tracks accept only audio items and caption tracks only caption items. Track and item IDs must be unique and cannot be renamed. session_data can change name, format (dimensions follow the format unless supplied), dimensions, fps (1–60), duration, background (color or image URL) and mediaLibrary, or replace the full tracks array. Targeted operations preserve other saved UI metadata. Nested values replace entire settings; use unset to remove optional item properties.

Clip fields cover transforms, source trims, speed (playbackRate 0.0625–16), volume (0–2), grading, audio effects, motion, text and caption styling. trimStart and trimEnd remove source milliseconds from the head and tail. originalDuration remains the source length and is required to recalculate a trimmed or retimed clip. Trim/speed changes on video and audio items recalculate duration unless explicitly supplied. The session duration grows to fit items but never shrinks automatically; supply duration to remove trailing background. Caption words use absolute timeline milliseconds; moving or reordering a caption shifts its words. Use transcribe_audio separately to derive word timings from speech.

Edits allow up to 64 tracks, 2000 items and 200 operations per request, with a 2 MB edit payload, 10 MB saved session and 30-minute timeline limit. The schema endpoint provides detailed bounds.

These tools edit saved state. Updated browser editors receive saved changes automatically while preserving the playhead and view. Unsaved manual edits pause autosave and show a conflict choice. Browser and agent writes both use revision checks. Saved settings do not guarantee every effect renders identically in all export paths; inspect the exported result before claiming visual parity.

Errors