Submit edit

Run an atomic edit (edit → frame regen → video sync) on an existing video

Overview

POST /v1/edits mutates an existing video with a natural-language instruction. A single call kicks off three internal phases — Claude rewrites the planner, frame images are regenerated for any changed scenes, and the video clips are restitched against the new planner. The endpoint returns immediately with an edit_id you poll with GET /v1/edits/{edit_id}.

This endpoint is asynchronous. The response confirms the edit was accepted (queued or processing); the full edit pipeline runs in the background and typically takes 30 seconds to a few minutes depending on how many scenes changed.

Endpoint

POST {API_BASE}/v1/edits

Your API_BASE is shown in the Developer tab of your dashboard. The default production base is https://api.knowlify.com.

Authentication

Send your key in the X-API-Key header. The key must own the target video_uuid — either as the user who created the video, or as an active member of the organization that owns it.

X-API-Key: kn_<64 hex chars>

See Authentication for full details on key issuance, rotation, and JWT alternatives.

Headers

X-API-Key · string · required

Your kn_<64 hex> API key.

Idempotency-Key · string

Opaque caller-chosen string. Replaying the same key within 24 hours returns the original response without creating a second edit. Use a fresh value per logical operation (e.g., a UUID); reuse it on retries of the same operation.

Request body

video_uuid · string · required

UUID of the video to edit. Must be a corporate_engine_v2 row owned by the API key’s user or organization.

edit_request · string · required

Natural-language instruction describing the change. 1–5000 characters. Examples: "Make scene 2 more dramatic with closer camera angles", "Replace the bird in scene 3 with a hawk", "Add a new closing scene that summarizes the topic".

reference_image_urls · string[]

Up to 5 reference image URLs to condition the edit. Each URL must:

• Use the https:// scheme.
• Resolve to a public IP (private, loopback, link-local, and reserved ranges are rejected).
• Return Content-Type: image/* and Content-Length ≤ 5 MB on a HEAD request.

One redirect hop is followed; the redirect target is re-validated end-to-end.

aspect_ratio · string

Optional aspect ratio override. One of "16:9" or "9:16". Defaults to the target video’s existing aspect ratio.

skip_content_safety · boolean · default: "false"

Reserved for admin keys. Standard API keys must leave this false; the content-safety scan always runs for external callers.

Response

A successful call returns HTTP 202 Accepted once the edit has been recorded and dispatched to the worker.

edit_id · string

Stable identifier for this edit. Pass to GET /v1/edits/{edit_id} to track progress and to POST /v1/edits/{edit_id} /revert to undo.

video_uuid · string

Echo of the video_uuid you submitted.

status · string

Initial status. "processing" when the worker can start immediately, "queued" when another edit on the same video is already in flight.

queue_position · integer

1-indexed position behind any other active or queued edits on the same video. 0 when this edit is the first to run.

Error codes

Code	Cause
400	The edit_request was rejected by the content-safety scan.
401	X-API-Key header missing or invalid.
402	Insufficient credits for the worst-case cost of the edit. See Credit cost. detail is "INSUFFICIENT_CREDITS: edit could cost up to <N>, have <M>".
403	The API key does not own video_uuid.
404	video_uuid does not exist.
409	The target video is still being built for the first time (e.g., pipeline_status is lowlevel or generating_frames) or has errored. Wait for the initial render to finish.
415	A reference_image_urls[] entry returned the wrong Content-Type, missing Content-Length, or exceeded 5 MB.
422	Pydantic validation failure (missing field, oversized edit_request, reference_image_urls[] longer than 5) or a reference URL failed the SSRF host check (non-https, private IP, second-hop redirect).
429	Per-caller rate limit exceeded. See Rate Limits.

All non-2xx responses share the standard envelope: { "detail": "<message>" }. See Errors for the full reference.

Code examples

curl

curl -X POST "https://api.knowlify.com/v1/edits" \
  -H "X-API-Key: kn_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440099" \
  -d '{
    "video_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "edit_request": "Make scene 2 more dramatic with closer camera angles.",
    "reference_image_urls": [
      "https://cdn.knowlify.com/assets/style-ref.jpg"
    ]
  }'

Example success response

{
	"edit_id": "e942890a-7776-4029-82d6-ce733d0a2cb2",
	"video_uuid": "550e8400-e29b-41d4-a716-446655440000",
	"status": "processing",
	"queue_position": 0
}

How edits work

Internally a single POST /v1/edits runs three phases in sequence inside one worker job:

1. Edit — Claude reads the current planner and rewrites the affected scenes based on edit_request. Sets pipeline_status to edit_complete.
2. Frame regen — first/last frame images are regenerated for any changed or added scenes. Sets pipeline_status to edit_pending_apply.
3. Sync — video clips for changed and added scenes are regenerated and stitched into the existing timeline, producing a new link and timestamps. Sets pipeline_status back to complete.

If the target video has never been fully rendered (no timestamps / link exists), phase 3 is skipped automatically. The edit lives in the planner and the next render will reflect it. result.video_synced on the poll response will be false in that case.

If Claude returns a clarifying question instead of an edit (a plan-mode response), the endpoint auto-confirms with "yes, proceed" up to twice. If a third call still returns a question, the edit terminates with status: "error" and error_message: "edit request was ambiguous; rephrase and retry.".

Credit cost

Phase 1 (the Claude edit itself) is free. Phases 2 and 3 are billed per scene that successfully regenerates, after the underlying provider call returns:

Phase	Cost per scene	Charged for
Frame regeneration	4 credits	Each Veo scene whose first/last frame is regenerated in phase 2.
Video clip (Veo/grok)	25 credits	Each Veo scene whose video clip is regenerated in phase 3 (same rate as the initial render).
Video clip (Remotion)	9 credits	Each Remotion scene that is re-rendered in phase 3.

You only pay for scenes that actually regenerate. A scene that fails partway through is never billed, and worker-level retries of the same edit are deduplicated so you cannot be charged twice for the same scene.

Pre-flight check

Before accepting the edit, POST /v1/edits computes a worst-case upper bound assuming every scene in the planner is touched:

upper_bound = (4 + 25) × veo_scenes  +  9 × remotion_scenes

If your account balance is below this number the request is rejected with 402 Insufficient Credits and no work is started. The actual charge after the edit completes is almost always lower — typically only one or a few scenes change.

If the target video has never been fully rendered, phase 3 is skipped (see the note in How edits work) and you are only charged for phase 2.

Next step

The response gives you an edit_id. Use it with GET /v1/edits/{edit_id} to track the edit through queued → processing → applying → complete, and POST /v1/edits/{edit_id}/revert to undo a completed edit.

Limits & errors

• 10 requests / 60 seconds per caller. See Rate Limits.
• One video per request; concurrent edits on the same video are queued serially via pending_edits[].
• Full status code reference: Errors.