Kinetic Film

The film format: timing rules, palette and fx, every block type (words, strike, counter, end) with its fields and limits, writing tips, the display formats (16:9, 9:16, 1:1) and an example spec that validates. Read it before writing a spec. Read-only.

No input parameters required.

Check a spec without saving it. Returns valid true with duration_s, total_beats, the film text and the normalised spec, or valid false with error as "path: reason" (for example "blocks[1].at: must be 6 (blocks follow each other without gaps or overlap)"). Read-only.

Save a spec as the new version of a film; creates the film when the film_key is new. The same spec again makes no new version (changed false). Returns film_key, title, version, duration_s, spec, embed_html and preview_html for the display options given. A refused spec returns 422 with "path: reason".

One film with its spec, embed_html and preview_html: the current version, or an earlier version. Takes the same display options as save. Read-only.

Films of this project, most recently changed first, without their specs: film_key, title, version, duration_s, created_at, updated_at; plus count and the maximum per project. Read-only.

Saved versions of a film, newest first: version, duration_s, note, created_at; plus the current version. The newest 30 versions are kept. Read-only.

Make an earlier version the current one again; it is saved as a new version, nothing is overwritten. Returns the same as save. Pages keep the film they were given: replace the block on the page with the new embed_html.

Delete a film and all its versions. Pages that embed it keep playing their own copy until you remove the block from the page.

Price and size of rendering a film version to an mp4 video, before you start it. Returns price_credits, width, height, duration_s, estimated_render_s, the owner's available_credits, can_render and, when it cannot, reasons (not switched on yet, free plan, not the owner, not enough credits). Nothing is reserved or charged. Read-only.

Render a film version to an mp4 video (H.264, 30 fps, no sound) plus a poster JPG, on paid plans, paid from the project owner's credits. Only the owner can start it; check the price with render_quote and get the owner's consent first. The render waits in a queue and takes about as long as estimated_render_s; follow it with render_status. The price is charged only when both files are stored; a render that fails, times out or is cancelled costs nothing. Files: films/<film_key>/<film_key>-v<version>-<width>x<height>.mp4 and .jpg (a new render of the same version and size replaces them). The same version at the same size again returns the earlier render for free (reused true) while its files are still there.

One render: status (queued, running, saving, done, failed, cancelled, expired), progress 0-100, queue_position while queued, error, and when done the video and poster with slug and url (url null for private files), bytes, charged. Poll every 10-20 s. Read-only.

Renders of this project, newest first, in the same shape as render_status. Read-only.

Cancel a render that is queued or running. Nothing is charged. Owner only.