Overview POST /v1/videos is the programmatic entry point for the Knowlify Animation Engine. A single call queues 1–50 video generation jobs and returns immediately with a job ID for each one. Videos render asynchronously in the background — use GET /v1/videos/{uuid}This endpoint is asynchronous. The response confirms each job was accepted (queued or parked); rendering itself takes minutes and is delivered out-of-band.
Endpoint POST {API_BASE}/v1/videos
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. Personal keys are scoped to your user; organization keys are scoped to a single org.
X-API-Key: kn_ < 64 hex char s >
See Authentication for full details on key issuance, rotation, and JWT alternatives.
Request body videos
VideoCreateItem[]
required
Array of 1–50 video specs to queue. Items beyond your concurrency limit are accepted but parked in a waiting list — see Rate Limits . Advisory only — when authenticating with an API key, identity comes from the key itself. Maximum 320 characters; must match [email protected] Optional organization scope. For API keys this must match the org the key belongs to (or be omitted). For JWT callers, the server verifies active membership.
VideoCreateItemShow VideoCreateItem fields
The instruction describing what the video should explain or show. 1–5000 characters.
Target video length in seconds. Range: 30–300.
Output aspect ratio. One of "16:9" (landscape) or "9:16" (portrait).
Style preset. One of: "instructional", "explainer", "corporate", "marketing", "narrative", "social".
Free-form direction applied to every scene (e.g., “minimal, brand-blue accents, sans-serif”). Maximum 5000 characters.
Optional brand palette. Allowed keys: primary, secondary, tertiary, accent. Each value must be a hex color (#fff or #ffffff). { "primary" : "#0066cc" , "accent" : "#ff6600" }
Voice provider ID for narration. Maximum 200 characters.
Display name for the chosen voice. Maximum 200 characters.
Free-form description of the desired narration style. Maximum 2000 characters.
Up to 20 reference images. Each entry can be an http(s) URL string or an object { "url": "..." }.
A single user-uploaded reference video (http(s) URL, ≤60s).
http(s) URL of a source PDF to draw content from.
Display name for the PDF (used for chat context). Maximum 500 characters.
Up to 50 image selections extracted from the PDF.
Internal mode flag. Leave as default unless instructed otherwise.
Skips the manual voiceover-approval step. Always true for programmatic calls.
Response A successful call returns HTTP 200 even when individual items fail — inspect each results[].status to know what to retry.
Always "ok" on a 2xx response.
Number of items in the request.
Items dispatched to a worker immediately.
Items accepted but waiting for a free concurrency slot.
Items that failed validation or queueing.
UUID of the authenticated caller.
Organization ID if the key/JWT is org-scoped, otherwise null.
One entry per request item, in the same order as videos. Position of this item in the original videos array.
The job ID — pass to GET /v1/videos/{uuid} to poll status.
Chat session ID for the job.
Direct link to the dashboard view for this job.
One of "queued", "parked", "already_processing", or "error".
Present when status is "parked" — 1-indexed position in your waiting list.
Present when status is "error" (e.g., "ITEM_FAILED").
Present when status is "error" — human-readable description.
Every successful response carries the current rate-limit window state:
X-RateLimit-Limit: 30 X-RateLimit-Remaining: 27 X-RateLimit-Reset: 42
Code examples curl -X POST "https://api.knowlify.com/v1/videos" \ -H "X-API-Key: kn_YOUR_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{ "videos": [ { "task": "Explain how HTTPS works in 30 seconds", "video_duration_seconds": 60, "aspect_ratio": "16:9", "video_type": "explainer", "color_palette": { "primary": "#0066cc", "accent": "#ff6600" } }, { "task": "Quarterly results recap", "video_duration_seconds": 45, "aspect_ratio": "9:16", "video_type": "corporate" } ] }'
Example success response { "status" : "ok" , "total" : 2 , "enqueued" : 2 , "parked" : 0 , "errors" : 0 , "user_id" : "5b9e...c1" , "org_id" : null , "results" : [ { "index" : 0 , "uuid" : "550e8400-e29b-41d4-a716-446655440000" , "session_id" : "550e8400-e29b-41d4-a716-446655440001" , "chat_url" : "https://create.knowlify.com/p/chat/550e8400-e29b-41d4-a716-446655440001" , "status" : "queued" }, { "index" : 1 , "uuid" : "550e8400-e29b-41d4-a716-446655440002" , "session_id" : "550e8400-e29b-41d4-a716-446655440003" , "chat_url" : "https://create.knowlify.com/p/chat/550e8400-e29b-41d4-a716-446655440003" , "status" : "parked" , "queue_position" : 1 } ] }
Next step Each accepted item returns a uuid. Use it with GET /v1/videos/{uuid}
Limits & errors
30 requests / 60 seconds per caller. See Rate Limits .
1–50 items per request; max 3 concurrent jobs per user/org (additional items are parked).
Full status code reference: Errors .
