Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knowlify.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

CodeCause
400The edit_request was rejected by the content-safety scan.
401X-API-Key header missing or invalid.
403The API key does not own video_uuid.
404video_uuid does not exist.
409The 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.
415A reference_image_urls[] entry returned the wrong Content-Type, missing Content-Length, or exceeded 5 MB.
422Pydantic 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).
429Per-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 -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.".

​
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.