---
title: "Every key, range and word a scene may use."
method: POST
path: "/api/agents/run/video_schema"
tags: ["Production engines"]
---

# Every key, range and word a scene may use.

`POST /api/agents/run/video_schema`

## Request

- Base URL: `https://tomorrowlives.com`
- URL: `https://tomorrowlives.com/api/agents/run/video_schema`
- Auth: HTTP bearer

Every key, range and word a scene document may use: the output, visual tracks of clips (designs, material fills, colours, gradients, titles and shots), the camera, audio (voices, sounds, music) and subtitles. Call this first when making a video, and video_examples for whole scenes to start from. A scene can hold: drawn pictures with groups, flips and a multiply blend (a shadow, a vignette, a night grade); characters who talk (cast, timed lines with their own reading, ducked music, subtitles made from the lines, a mouth that moves on the words and eyes that blink); shots with people on paths, action beats (guard, strike, hit, fall, get-up) and gestures on cue (a wave, a point, a nod), animals and forms, and a camera that follows, orbits or cranes; music with a melody, a lead instrument and tempo changes; and sounds that move across the ears. Designs go inline in a scene; a path to a file is refused. A shot can stand in a world of ours, named by id and never by a path: copperside and low-quarter. In a scene it is a shot subject {"kind": "world", "id": "copperside", "at": [x, 0, z], "radius": metres}; copperside is Brasshollow's Copperside, the streets and buildings of its start zone around that point, and low-quarter a small generated quarter. A street draws its crowd by default, and the crowd is most of its price: set extra.crowd to false (or {"most": 0}) for the plain price, or {"most": 3} for a few people. A clip in a world costs 5 units more than a flat one and 0.2 a frame for a street; one that draws the crowd 25 more and 1.2 a frame. video_examples has copperside-street, 30 units. Costs no units.

## Request body

- object

## Response `200`

The job's result and files

- Job
  - `job` string
  - `verb` string
  - `units` integer
  - `ms` integer
  - `result` unknown
  - `files` object[]
    - `name` string
    - `bytes` integer
    - `content_type` string
    - `url` string
    - `url_expires_at` string, date-time

## Other responses

- `400`: The input is not valid
- `401`: No valid API key
- `402`: A pass or a payment is needed: a queued render on the free plan, a unit pack on the free plan (pass_required), a card plan's past-due renewal, or, on the free plan, an owner who has not confirmed their email yet (owner_unconfirmed; a pass needs no confirmation); or a payment did not go through (payment_failed, payment_token_unusable), and nothing was charged
- `403`: The account is suspended, the paying card is not from the United States (region_not_supported), or the address named as its owner said it is not theirs and costed runs are paused until a new owner is named (owner_removed)
- `413`: The input or the output is over its cap; a job stopped by the output cap is not charged
- `422`: The engine refused the input, a limit of the service's refused it (error: video_limit or pull_limit) or stopped the job, or the content policy refused the input (error: content_policy)
- `429`: A limit was hit; reset_at says when it lifts (also in Retry-After)
- `503`: The engines are busy or not installed
- `504`: The job ran past its time and was stopped

---

[API](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines.md) · [All operations](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines/llms.txt) · [OpenAPI document](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines/revisions/afc3d67322ac?raw)