Tutorial

Generated Assets

What an asset is, how generate and lock work, and where to go next.

Checked 2026-10-07

An Asset is one image your code declares as a recipe: a kind, a prompt and a few parameters. :generate makes the variants the recipe asks for, once; :lock returns the assets.lock file you commit, which pins every asset to the exact files that were made; each file is served from an immutable URL named by its content hash. There is nothing to deploy and no image model to sign up with: one key in your project is enough.

#What an asset gives you

• The recipe is the identity. An asset's id is a 16-hex key computed from its recipe, so the same recipe is always the same asset, and generating it again costs nothing. Change the prompt and it is a new asset.
• Generated once, then locked. The lock names each variant's SHA-256, so a build ships exactly the files you reviewed, on every machine.
• Served by content hash. Each variant's url is public, immutable and cacheable for a year; a new file is a new URL, so there is nothing to purge.
• Review in the API. Approve a variant to record who chose it; reject one and the next :generate fills its slot; retire one and its URL answers 404.
• Bounded calls. A generate works within a fixed time; call it again until pending is 0. It is idempotent, so a CI retry is safe.
• Images today. Recipes of kind image are generated now, 64 to 2048 pixels a side and 1 to 8 variants. Other kinds (sfx, music, video, character, voice) and images drawn from a character are recorded and answer unsupported until they are built.

#Names and ids

Asset

orgs/{org}/projects/{project}/envs/{env}/assets/{key}

Asset key

16 lowercase hex characters, from the recipe

Asset id

ast_<cell><ulid>

Variant

its content_hash, 64 lowercase hex characters

#The scopes

• assets:write — :generate, and approving, rejecting and retiring a variant.
• assets:read — reading assets, :lock and :export.

Generation is billed per image stored; an asset that already exists is not generated again. Keys and scopes covers the two kinds of key.