Create video

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} to poll, or subscribe to Supabase realtime for live updates.

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 chars>

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

Request body

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.

string

Advisory only — when authenticating with an API key, identity comes from the key itself. Maximum 320 characters; must match [email protected].

string

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.

`VideoCreateItem`

Show VideoCreateItem fields

string

required

The instruction describing what the video should explain or show. 1–5000 characters.

integer

required

Target video length in seconds. Range: 30–300.

string

default:"16:9"

Output aspect ratio. One of "16:9" (landscape) or "9:16" (portrait).

string

Style preset. One of: "instructional", "explainer", "corporate", "marketing", "narrative", "social".

string

Free-form direction applied to every scene (e.g., “minimal, brand-blue accents, sans-serif”). Maximum 5000 characters.

object

Optional brand palette. Allowed keys: primary, secondary, tertiary, accent. Each value must be a hex color (#fff or #ffffff).

{ "primary": "#0066cc", "accent": "#ff6600" }

string

Voice provider ID for narration. Maximum 200 characters.

string

Display name for the chosen voice. Maximum 200 characters.

string

Free-form description of the desired narration style. Maximum 2000 characters.

(string | object)[]

Up to 20 reference images. Each entry can be an http(s) URL string or an object { "url": "..." }.

string

A single user-uploaded reference video (http(s) URL, ≤60s).

string

http(s) URL of a source PDF to draw content from.

string

Display name for the PDF (used for chat context). Maximum 500 characters.

object[]

Up to 50 image selections extracted from the PDF.

boolean

default:"true"

Internal mode flag. Leave as default unless instructed otherwise.

boolean

default:"true"

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.

string

Always "ok" on a 2xx response.

integer

Number of items in the request.

integer

Items dispatched to a worker immediately.

integer

Items accepted but waiting for a free concurrency slot.

integer

Items that failed validation or queueing.

string

UUID of the authenticated caller.

string

Organization ID if the key/JWT is org-scoped, otherwise null.

object[]

One entry per request item, in the same order as videos.

Show result fields

integer

Position of this item in the original videos array.

string

The job ID — pass to GET /v1/videos/{uuid} to poll status.

string

Chat session ID for the job.

string

Direct link to the dashboard view for this job.

string

One of "queued", "parked", "already_processing", or "error".

integer

Present when status is "parked" — 1-indexed position in your waiting list.

string

Present when status is "error" (e.g., "ITEM_FAILED").

string

Present when status is "error" — human-readable description.

Response headers

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"
      }
    ]
  }'

const res = await fetch("https://api.knowlify.com/v1/videos", {
  method: "POST",
  headers: {
    "X-API-Key": "kn_YOUR_KEY_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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",
      },
    ],
  }),
});

const data = await res.json();
console.log(data.results.map((r) => `${r.uuid} → ${r.status}`));

import requests

resp = requests.post(
    "https://api.knowlify.com/v1/videos",
    headers={"X-API-Key": "kn_YOUR_KEY_HERE"},
    json={
        "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",
            },
        ]
    },
    timeout=30,
)
resp.raise_for_status()
for r in resp.json()["results"]:
    print(r["uuid"], r["status"])

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} to track render progress until the job is complete.

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.

Overview

Guides

Endpoints

Overview

Endpoint

Authentication

Request body

`VideoCreateItem`

Response

Response headers

Code examples

Example success response

Next step

Limits & errors

​Overview

​Endpoint

​Authentication

​Request body

​VideoCreateItem

​Response

​Response headers

​Code examples

​Example success response

​Next step

​Limits & errors

Overview

Endpoint

Authentication

Request body

`VideoCreateItem`

Response

Response headers

Code examples

Example success response

Next step

Limits & errors