POST /v1/recipes/{id}/runs

Run a recipe

Answers the recipe's questions and starts it. An `arm` or `reprompt` recipe makes one generation; a `run` recipe starts a run you can read and cancel at `/v1/runs/{id}`. Pass `wait` to hold the response until it settles.

Permission

A key with chosen permissions needs generation.write. A key made with every permission may always call it. It can spend: send an Idempotency-Key so a retry replays the first answer.

Parameters

id (path)string · required
uuid
waitinteger · optional
Hold the response up to this many seconds until the work settles. 0 answers at once.
default 0 · min 0 · max 60
Idempotency-Key (header)string · optional
Any string up to 255 characters. Send the same value to retry a request without spending twice; a different body under a used key is refused with 409.
up to 255 characters

Body

promptstring · optional
The idea, in the words the recipe's `prompt` asks for.
up to 4000 characters
inputsobject · optional
By key. On an `arm` or `reprompt` recipe, each of its `inputs` takes a list of media (`{ "type": "upload", "upload_id" }`, `{ "type": "generation", "generation_id" }`) or one Subject (`{ "type": "subject", "subject_id" }`). On a `run` recipe, each of its `run_inputs` takes the value its type asks for.
choicesobject · optional
One option `value` per choice, by key; a list where `max_picks` is above one.
modelstring · optional
Another model of the recipe's medium. Not for `run` recipes.
up to 80 characters
runs_onstring · optional
Who pays: "credits", or the vendor of one of your own keys ("replicate", "fal", …). Leave out to follow the payer order set in Settings → Agents.
up to 40 characters
webhook_urlstring · optional
Where to POST a signed event when this settles. HTTPS on the default port; see Webhooks in the API description.
up to 2048 characters · uri

Response: RecipeRun

201 · What running a recipe started.

object"recipe_run"
recipe_idstring
uuid
runany | null
The run a `run` recipe started; null for `arm` and `reprompt`, which make one generation.
generationsGeneration[]
What it made: the one generation, or what the run has made so far.

Example

The required fields only, each a placeholder. Replace them before sending.

curl -X POST "https://api.meetkuro.com/v1/recipes/<id>/runs" \
  -H "Authorization: Bearer $KURO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"<prompt>"}'

import { Kuro } from "@meetkuro/sdk";

const kuro = new Kuro(); // reads KURO_API_KEY
await kuro.recipes.run("<id>", { prompt: "A portrait of a fisherman" }, { wait: 60 });

Every operation