POST /api/v1/runs
Run a recipe on one file — one saved on the Workbench, or one written inline.
Same rules as the Workbench: a step in the wrong place, an option a skill doesn’t have, or a paid skill the account can’t afford is refused before anything is charged. Each skill step is charged as it starts and refunded if it fails.
There is no list endpoint. Start with POST, read one back with GET /api/v1/runs/{id}.

A recipe is the steps on the Workbench, run top to bottom. Copy as code under the steps hands out this call.
Inputs
A recipe’s inputs are the{{names}} written into its steps’ prompts and options: a title, a topic, an avatar. Send a value for each as inputs, and every {{name}} is filled in before the steps are checked:
GET /api/v1/recipes/{ref} lists a recipe’s inputs under inputs, each with its kind (text, long_text, number, link or choice), whether it is required, its default and, for a choice, its choices. An input with no settings of its own is text, and required. You set a saved recipe’s inputs on the Workbench.
- A required input with no default, left out, is
400 missing_input, andparamnames it. - A value that doesn’t fit its kind is
400 bad_input. - A name the steps don’t use is
400 unknown_input, so a typo is said rather than dropped.
{{Product Name}} is product_name. In a multipart form, send inputs as a JSON string, or one field per input named inputs[product_name]. Steps written inline take inputs the same way. A batch fills the same names from its rows instead.
Run one version of a recipe
Every time a saved recipe’s steps change on the Workbench, it gets a new version: 1, 2, 3. A rename isn’t a new version. A run takes the latest unless you name one, so an edit on the bench changes what the next call runs. To keep a call on the steps you tested, name the version:"recipe": "3f0c9a1e-…", "version": 3 does the same. GET /api/v1/recipes/{ref} shows a recipe’s version (the latest, or the one in the ref), and its run.body names the version when you asked for one. The run says what it ran:
null for steps sent inline, and version is null for a ready-made recipe, which has none. A version the recipe never had is 404 recipe_version_not_found, and its message names the latest. Older versions are kept, and History on the recipe’s tile in the app lists them with Restore. Restoring saves the old steps as a new version on top, so nothing is lost.
Several formats from one run
Sendoutput as a list, up to 5 entries, and the run hands back one file per entry:
outputs lists them in the order sent: shoe.png, then shoe.webp. Two entries of the same format are numbered: shoe.webp, shoe-2.webp. The extra files are free, as a Convert step is.
In a list, format takes png, jpeg or webp, videoFormat takes mp4, hevc, webm or prores, and audioFormat takes mp3, m4a, wav, flac or ogg. Anything else is 400 bad_option, before anything runs. An entry that changes nothing on the finished file, such as a picture format on a video, makes no file. POST /api/v1/batches, run_recipe and estimate take the same list.
Price the steps first
Senddry_run=true and every step is checked exactly as a run checks it — order, options, plan — and priced with the same rule the charge uses. Nothing is charged or run, and the file is thrown away once it has been measured. The answer has the same shape as a single skill’s dry run, with one breakdown line per step:
exact is then false.
With a test key, a run is checked the same way and then comes back complete at once, with "test": true, "livemode": false, credits_charged: 0 and a stand-in of whatever the steps would hand back at the end.
Workbench and saved recipes drop unknown options. The API doesn’t — an unknown option is 400 bad_option, and a tool no skill answers to is 400 unknown_skill. The plan’s fences — AI steps a run, source length — come back as 403 plan_limit before anything is charged. See Errors.
See Recipes for the six catalogue recipes.
Set "nested": true (or "indent": true) on a step to run it only on what the generation above it made. Same rule as indenting a step on the Workbench.
