---
title: "One frame of a scene as a PNG (queued)."
method: POST
path: "/api/agents/run/video_still"
tags: ["Production engines"]
---

# One frame of a scene as a PNG (queued).

`POST /api/agents/run/video_still`

## Request

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

Renders one frame of a scene at t seconds as a PNG at the scene's size: the way to look at a moment (just after a transition, mid-reveal, the last frame) before rendering the whole video. Costs 1 unit, plus a shot's price when the scene has shots (3 plus 1 for each 1.6 megapixels). It runs as a queued job: the answer is 202 with a job id at once, and GET /api/agents/jobs/<job> (or the MCP tool job) says when it is done and signs its files. A queued call is refused on the free plan with 402: its units buy only calls that answer at once, and queued jobs need a paid plan (a pass or the card plan). Returns still.png.

## Request body

- object
  - `scene` object, required: A scene document written inline: output (size, frame rate, length), tracks of clips, optional cast and lines, audio and subtitles. Start from video_examples and read video_schema for every key.
  - `t` number, required: The moment to draw, in seconds from the scene's start.

## Response `202`

Queued: the job id, its price and where to poll. Poll GET /api/agents/jobs/{job} until it is ok, refused or failed.

- QueuedJob: A queued job, as submitted. Its units already count against the allowance; a job the engine refuses, one the server never ran, or one whose files pass the 50 MB cap (error output_too_large) is not charged.
  - `job` string
  - `verb` string
  - `status` 'queued'
  - `units` integer
  - `created_at` string, date-time
  - `poll` object
    - `method` string
    - `path` string
    - `wait_max_s` integer
    - `hold` string
  - `retry_after_s` integer: When to ask first, in seconds; also the Retry-After header
  - `estimate` unknown

## 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)