Create Training videos

These pages describe the Training API on dev, where authenticated creation, editing, downloads, revert, and website brand lookup have been tested live. Production availability is not confirmed. Your API service and worker must both run the updated code. See Testing and availability.

POST {API_BASE}/v1/videos Send X-API-Key and Content-Type: application/json. The response is asynchronous: HTTP 200 confirms the batch was handled, not that every item succeeded or finished rendering.

curl --fail-with-body "$API_BASE/v1/videos" \
  -H "X-API-Key: $KNOWLIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"videos":[{"task":"Train employees to lock their screen before leaving their desk.","video_duration_seconds":30,"video_type":"training","video_quality":"standard","aspect_ratio":"16:9"}]}'

Request

Field	Type	Rules
`videos`	array, required	1–3 video specifications
`org_id`	string, optional	Omit for API keys; if supplied it must match the key’s organization scope
`email`	string, optional	Advisory only; never changes the authenticated identity. Maximum 320 characters; nonempty values must have email syntax

Video specification

Field	Type	Rules
`task`	string, required	1–300 characters after trimming; whitespace alone is rejected
`video_duration_seconds`	integer, required	Requested duration target: 10–14400 seconds at schema level; your account’s duration entitlement can impose a lower maximum. Actual output length depends on generated narration and rendering; this is not an exact-length guarantee
`video_type`	string	Set to `training` for this workflow
`aspect_ratio`	string	`16:9` (default) or `9:16`
`video_quality`	string	Use `standard` or `max`. Legacy `high` and `ultra` values remain accepted but normalize to standard
`style_library_id`	string	An ID from the style library; unknown IDs return 422
`global_style_prompt`	string	Up to 5000 characters of visual direction
`color_palette`	object	Optional `primary`, `secondary`, `tertiary`, `accent`; values must be three- or six-digit hex colors with `#`. Omit missing colors rather than sending null
`brand_fonts`	object	Optional `title`, `body` (each up to 200 characters), and `files` (up to eight font files)
`colors_locked_by_user`	boolean	Default false; true when the user explicitly selected the palette
`disable_scraped_images`	boolean	Default false; true when the user has curated the reference images
`reference_image_urls`	array	Up to 20 public HTTPS image URLs or owned imports, as strings or objects containing a `url`
`reference_video_url`	string	Optional public Knowlify-hosted HTTPS reference video URL; use a clip of at most 60 seconds
`pdf_url`	string	Optional direct public HTTPS source PDF URL, up to 32 MB
`pdf_file_name`	string	Optional PDF display name, up to 500 characters
`pdf_selected_images`	array	Unsupported by the public API; use `reference_image_urls`
`voice_id`, `voice_name`	string	Optional voice selection from the voice library, each up to 200 characters
`voice_description`	string	Optional voice direction, up to 2000 characters
`variant_index`, `variant_count`	integer	Optional variant metadata: index 0–4; count 1–5
`is_rxv`	boolean	Defaults to true; leave at the default
`auto_approve_voiceover`	boolean	API jobs automatically approve voiceover; leave at true

Each brand_fonts.files entry requires family (1–200 characters) and a public Knowlify-hosted HTTPS url (up to 2048 characters). Optional weight is a string up to 100 characters; optional source is google or custom. See Website brand lookup for selecting and applying brand context. Passing a website to the lookup does not automatically attach its assets to a video.

Response

HTTP 200 returns status: "ok", total, enqueued, parked, errors (a count), user_id, org_id, and results. Each result contains its zero-based index, uuid, and status:

queued: dispatched for processing; includes session_id and chat_url.
parked: accepted and waiting for capacity; also includes queue_position.
already_processing: this job was already present in processing state.
error: inspect code and message. See Errors.

{
  "status": "ok",
  "total": 1,
  "enqueued": 1,
  "parked": 0,
  "errors": 0,
  "user_id": "11111111-1111-4111-8111-111111111111",
  "org_id": null,
  "results": [{
    "index": 0,
    "uuid": "22222222-2222-4222-8222-222222222222",
    "session_id": "33333333-3333-4333-8333-333333333333",
    "chat_url": "https://knowlify-dev.up.railway.app/p/chat/33333333-3333-4333-8333-333333333333",
    "status": "queued"
  }]
}

These are illustrative IDs. Use the returned uuid to poll rendering. Invalid request shapes return 422 for the whole batch; account-specific duration failures can appear as individual errors in a 200 response. Creation has no documented idempotency guarantee. After a timeout, check the dashboard before resubmitting to avoid duplicate videos.

Three-video capacity limit

At most three API videos may be queued or generating per personal account or organization. This includes Enterprise and is shared across requests and keys for that scope. If your whole batch cannot fit, the API returns 429 with VIDEO_GENERATION_CONCURRENCY_LIMIT before creating any videos. Respect Retry-After and wait for an existing video to finish. See Rate limits.

Reference safety

Training reference images must be public HTTPS PNG, JPEG, or WebP files, or imported images owned by the caller’s workspace. Public images are copied into caller-owned storage before use. Private images belonging to another workspace are rejected. Direct images must fit the 10 MB and 25-megapixel limits and must not redirect. PDF references must return a PDF directly over public HTTPS, without redirects, credentials, or custom ports. Downloads are capped at 32 MB and a bounded timeout. Video and font-file references require publicly readable Knowlify-hosted HTTPS assets. Use reference_image_urls instead of nested pdf_selected_images. Use video_type: "training" for Training. The legacy Training value explainer is normalized to Training. UGC, animated ads, and commercials use the Marketing API. Voice identifiers must come from the caller’s voice catalog.

Overview

Guides

Endpoints

Create Training videos

Request

Video specification

Response

Three-video capacity limit

Reference safety

​Request

​Video specification

​Response

​Three-video capacity limit

​Reference safety

Request

Video specification

Response

Three-video capacity limit

Reference safety