---
title: "One frame of a shot as a PNG, drawn in the game's light (queued)."
method: POST
path: "/api/agents/run/raster_render"
tags: ["Production engines"]
---

# One frame of a shot as a PNG, drawn in the game's light (queued).

`POST /api/agents/run/raster_render`

## Request

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

Renders a shot (a camera through the engine's world: forms from the sculptor, people and animals from the rig, open country, primitives, under the game's own sky, sun, shadow and haze) at t seconds as shot.png. width and height (both or neither) set the size, else the shot's own; at most 1920 by 1080 either way up. Costs 3 units plus 1 for each 1.6 megapixels: 4 at 1280x720, 5 at 1920x1080. A shot can draw a world of ours, named by id and never by a path (copperside and low-quarter): a zone subject {"kind": "zone", "world": "copperside", "zone": "city", "cut": [x, z, radius], "crowd": false} draws a street (copperside's start zone is city), and a terrain subject with the same world key draws its country. A street draws its crowd by default, which is most of its price: a still in a world costs 5 units more, one that draws the crowd 26.2 more again. 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).

## Request body

- object
  - `shot` object, required: A shot document written inline: a camera, the sun and air, and subjects. raster_schema lists every key.
  - `t` number: The moment to draw, in seconds from the shot's start, for a shot with motion.
  - `width` integer: Output width in pixels, 16 to 1920; overrides the shot's own.
  - `height` integer: Output height in pixels, 16 to 1920; overrides the shot's own.

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