Skip to content

Recipes (beta)

Beta

Recipes are new, and their API may still change. Everything else on this site is stable.

A recipe is a pipeline saved under a name: its inputs, its steps - each a model and the input it gets - and what it returns. Once it works, run it again on new inputs, run it over a whole dataset, or change one step and compare the two versions.

Save one

curl -X PUT $API/v1/recipes/find-damage -H "$AUTH" -H "Content-Type: application/json" -d '{
  "definition": {
    "inputs": {"photo": {"type": "image"}},
    "steps": [
      {"name": "boxes", "model": "sam3-segment",
       "input": {"image": {"$input": "photo"}, "objects": [{"id": "box", "text": "cardboard box"}]}},
      {"name": "cut", "model": "image-crop",
       "input": {"image": {"$input": "photo"}, "boxes": {"$step": "boxes"}}},
      {"name": "check", "model": "gemini-3.8-flash", "over": {"$step": "cut", "path": "images"},
       "input": {"image": {"$item": ""}, "prompt": "Is this box damaged? Answer yes or no, then why."}}
    ],
    "output": {"boxes": {"$step": "boxes"}, "verdicts": {"$step": "check"}}
  }
}'
  • {"$input": "photo"} is one of the recipe's inputs.
  • {"$step": "boxes"} is an earlier step's answer.
  • A step with over runs once for each item of a list - here each cropped picture - and {"$item": ""} is the item ({"$item": "label"} one part of it).

It is checked whole when you save it - the models exist, the fields are ones they take, the references point at real steps - and kept as version 1. Saving a different definition under the same name makes version 2.

Run it

curl $API/v1/recipes/find-damage/runs -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"inputs": {"photo": "med_..."}}'

The server carries the run to the end; follow it at GET /v1/recipe-runs/{id}, whose output is the recipe's output once it has finished.

Run it over a dataset

POST /v1/recipes/{name}/batches with a list of inputs - up to 10,000 - runs the first few as a priced trial, shows their results and the projected total, and waits. POST /v1/recipe-batches/{id}/confirm runs the rest, a few at a time. Failed items can be retried on their own, and the results come back as JSON, JSONL or CSV.

Change it and compare

GET /v1/recipes/{name}/diff?a=1&b=2 says which steps changed and which would run again. POST /v1/recipe-runs/{id}/compare runs another version on an earlier run's inputs, reusing the answers of every step that did not change - so you pay only for what changed - and GET /v1/recipe-runs/{id}/comparison puts the two outputs side by side.

Every endpoint is in the API reference.