Recipes

Each recipe is one complete task: every request, every response, what to check between calls, and the durable handle you keep at the end.

They build on each other. Read them in order the first time — the read is the foundation for the write, and the write is the foundation for generation.

“Recipe” means two different things in Gavana, and both appear on this page. A Recipe with a capital R is a reusable workflow in the Gavana Recipe Library, run through POST /recipes/{recipeId}/runs. A recipe on this page is a documentation walkthrough. The last recipe on this page is a walkthrough of running a Recipe.

The four

Recipe	What you end up with	Spends credit
Read a canvas	The full graph, its revision, and a map of node handles you can act on	No
Apply a revision-safe batch	New and modified nodes, and the `resolvedIds` map linking your names to real handles	No
Generate and observe an image	A durable `asset:` and the `node:` it was written into	Yes
Run a Recipe with a webhook	Typed outputs with durable handles, delivered to your endpoint	Yes

Every task in this API is the same five moves:

Discover

Read the thing you are about to reference — the canvas, the Recipe’s declared ports, the Action’s parameter schema, the model catalogue. Never guess an identifier or a parameter name.

Validate

Where a dry run exists, use it. validateOnly: true on a canvas batch runs the real engine, writes nothing, consumes no idempotency key, and needs only canvas:read.

Confirm

For anything destructive or paid, get explicit approval in the current turn. Show what will be deleted or what will be spent, in the terms the person cares about.

Execute

One call, carrying baseRevision where the operation takes one and an idempotencyKey derived from the intent.

Observe and store

Poll the run: handle or receive the signed callback, then store the durable asset: and node: handles. Run records expire; those handles do not.

What “durable” means here

The distinction runs through all four recipes and is the single most common source of a broken integration.

Handle	Lifetime
`asset:` · `node:` · `canvas:` · `connection:`	Durable. Store these.
`run:` · `job:`	Temporary observation records with their own retention. Poll them, then discard them.
`previewUrl`	A short-lived scoped capability to view one image. Never store one.
Cursors and revisions	Valid for one continuation or one compare-and-set. Never store one.

If you find yourself persisting a run: handle as the identifier for a generated image, you have stored the receipt instead of the goods.

Before a paid recipe

The two paid recipes are marked. Before the first billable call in a session:

Say which operation will be charged, and roughly what it will produce.
Get approval in the current turn. Approval for one run is not approval for the next one, a retry, or a larger batch.
On failure, read failure.retryable, surface it, and ask again. Never auto-retry paid work.
Report what was actually spent when the task finishes.

Deterministic Image Actions — resize, crop, aspect ratio, side-by-side, text, overlay, colour grade, rotate — carry chargedCost: 0 and are exempt. If the change you need is a raster transformation rather than a new image, an Action is both free and exactly reproducible.