API reference

Conventions

Every /v1/* endpoint requires the Authorization: Bearer sk_... header. Errors come back as JSON with an error flag and a message:

{
  "error": true,
  "message": "length must be a positive multiple of 30 seconds, at most 360"
}

Generation endpoints are rate limited to 20 requests per minute. All other endpoints share a 200 per minute limit.

Create an explainer

Starts a generation and returns 202 Accepted with the queued record. Poll get an explainer until it is ready.

{
  "input": "Explain how DNS resolves a domain name",
  "length": "0:30",
  "aspect": "16:9",
  "voice": "sketchie:sulafat",
  "language": "en"
}

Returns the explainer record: id, status, prompt, lengthSeconds, voice, language, aspect, videoUrl (null until ready), and sceneGraph (null until generated). A 400 comes back for an empty input with no source, a malformed length, or an invalid aspect, preset, fillMode, or language.

Get an explainer

Returns the full record: current status, the videoUrl once ready, the editable sceneGraph, the version history (versions), and the head version's scene chunks. A missing id returns 404.

List explainers

Lists the calling key's explainers, newest first. Scoped to the key's owner. limit clamps to 1 through 100 (default 50). Returns lightweight summaries (no scene graph or versions). Use get an explainer for the full record.

Edit an explainer

The editability wedge. Turn a plain-language instruction into a targeted re-render. Only the affected scenes re-render, producing a new version. Returns 202 with the queued version. Poll get an explainer until the head version is ready. This appends to the existing video, so it does not consume another free-video creation slot. The first re-render of each video is free. Later re-renders use paid-plan minutes, and free accounts are asked to start a plan. The explainer must already be ready (otherwise 409).

{ "instruction": "Make the title scene shorter and warmer" }

Revert to a version

Re-points the head at an earlier ready version and mirrors its graph and video onto the record. The target must be a ready version with a video (otherwise 409).

{ "versionId": "..." }

Live status stream

A Server-Sent Events stream (text/event-stream). Open one connection and every status transition on any of your explainers arrives as an event: status frame, so you can update a "video ready" state the moment the worker finishes instead of polling. The stream is scoped to your key's owner.

Voices

The narration voice catalog. Optional ?language=<code> filters to voices native to that language. Returns voices (each with a friendly name, the id to pass as voice, language, isDefault, and a playable preview_url) plus the global default. See Voices.

Languages

The supported narration languages, as { code, label, native }. Every code is a valid language on create. See Languages.

Account state

Returns videosGenerated (lifetime), the account image, and isAdmin. Requires authentication.

Billing status

Requires authentication and returns 200 for both free and paid accounts. A free account returns plan: "free" with videoAllowance, videosUsed, and videosRemaining. A paid account also returns planLabel, billingInterval, trialStatus, quotaMinutes, minutesUsedThisPeriod, minutesRemaining, and bonusMinutes.

Runtime config and health

Public. Returns { "authEnforced": true }. A liveness check lives at GET /health.