Ops
The catalogue of atomic operations: what POST /api/v1/jobs accepts in op, with each op's parameter contract, its price as data, an example request and the endpoint that runs it synchronously, if any. Read it instead of carrying a list of op names. AI ops charge credits per item; deterministic ops count against the plan's processing allowance; a sync op names the endpoint that answers it. No credential needed — an agent can read the catalogue before it has a key.
2 endpoints under /api/v1/ops. What every call shares is on the REST overview, and what they are for — with the calls for every SDK, the CLI and MCP — on Ops & models. * marks a required field.
List every atomic op with its parameter contract
GET /api/v1/ops
Every atomic op, with what a program needs to call it without a list of its own. Submit one with POST /api/v1/jobs {"op": "<name>", "assetIds": [...], "parameters": {...}}, priced first with ?dryRun=true. Chaining ops is a list of steps — inline as steps on POST /api/v1/jobs, or saved as a preset (POST /api/v1/presets). Answers without a credential.
What each entry carries:
params— the parameter contract: name → type, bounds, default, descriptionpricing— the price as data:basis(per_item·process_quota·free); for an AI op,defaultModelis that model's published price (the recordGET /api/pricing/image-modelspublishes) withmarkupandcreditsPerUsd; for a deterministic op,processLimitis the allowance per billing period by plan (-1 unlimited)example— one complete, validatedPOST /api/v1/jobsbody with a placeholder asset id: copy it, swap the id. Absent for a sync op, which is not a jobmodelCategory— AI ops: the category amodelmust carry (GET /api/v1/ai-models→categories) to run the optypicalSeconds— how long one item usually takes as a job on the default model: a measured hint for sizingwait, not a promise; absent where nobody has measuredsyncEndpoint— the endpoint that runs the op while you wait; absent when there is none
USE THIS WHEN:
- Building a tool list or an operation dropdown
- Checking a request's parameters before submitting it
Returns 200 — data is OpDefinition[]
One op's contract
GET /api/v1/ops/{op}
The catalogue entry of one op, as GET /api/v1/ops lists it: its parameters, its price, an example request and its synchronous endpoint. Answers without a credential.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| op (required) | path | string | The op's name, as op in the catalogue |
Returns 200 — data is OpDefinition
The op's entry
Errors
| Status | Code and when |
|---|---|
| 404 |
|
Objects
Each described once; a linked type is another object on this page.
ImageModelPrice
A model's published price: ours, after markup, beside the provider's own list price
| Field | Type | Description |
|---|---|---|
| categories | string[] | What the model is sold for — an op's modelCategory is one of these |
| description | string | What the model does |
| id | string | The model's id, as model names it |
| name | string | The model's name |
| priceFrom | string | Our lowest price per image, in USD, as a decimal stringe.g. "0.0024" |
| priceRange | string | Our price per image, or its range, written for a persone.g. "$0.006 - $0.253" |
| providerPrice | string | The provider's own list price per image, in USD, before our markup — the cheapest end when the price has a range |
| providerPriceRange | string | The provider's list price across the same span as priceRange, for a model whose cost depends on a parameter; absent when one number covers it |
| series | string | The provider family |
OpDefinition
One atomic op: what it does, how to call it, what it costs and whether it can run while you wait
| Field | Type | Description |
|---|---|---|
| defaultModel | string | AI ops: the model a request that names none runs on; its price is pricing.defaultModel |
| defaultPrompt | string | analyze only: what it asks when neither the request nor its preset gives a prompt |
| defaultSchema | object | analyze only: the answer's JSON Schema when neither the request nor its preset gives parameters.schema |
| description | string | What the op does, in one sentence |
| endpoint | string | A sync op: the endpoint that answers it instead of a job |
| example | object | One complete POST /api/v1/jobs body that runs this op, with a placeholder asset id — it has passed the same validator a submit does. Absent for a sync op |
| jobType | string | The job type the op runs as; absent for a sync op |
| kind | string | ai runs a model and is charged credits per item; deterministic is an image pipeline, counted against the processing allowance; sync is answered by an endpoint, never a jobone of ai · deterministic · sync |
| maxInputEdge | integer (int32) | AI ops: the longest edge, in pixels, an input image is scaled down to before the default model sees it; another model's is its max_input_edge in GET /api/v1/ai-models |
| modelCategory | string | AI ops: the category a model must carry (GET /api/v1/ai-models → categories) to run this op; any other model is 400 invalid_param |
| op | string | The op's name — what op takes on a job, a preset step or a synchronous calle.g. "remove_bg" |
| params | object | The parameter contract: name → {type, enum?, min?, max?, default?, description}. A deterministic op refuses any other parameter with 400 invalid_param |
| pricing | OpPricing | How the op is priced, as data; the exact price of one request is the dry run |
| produces | string | What a step of this op hands to the next: an image, or a JSON answer — which only a last step can produceone of image · json |
| requiresAssets | boolean | Whether a job of this op needs assetIds |
| requiresPrompt | boolean | Whether a job of this op needs a prompt |
| syncEndpoint | string | The endpoint that runs the op while you wait — bytes in, bytes out, nothing stored — or absent when it has none. AI ops never do: a model call needs a job to own its retry and refund |
| typicalSeconds | integer (int32) | How long one item usually takes as a job, submit to terminal, on the default model — a measured median for sizing wait, not a promise. Absent where nobody has measured it, which never means fast |
OpPricing
An op's price as data: the basis, and the numbers behind it read from the catalogues that own them
| Field | Type | Description |
|---|---|---|
| basis | string | per_item: credits per output item at the model's USD price · process_quota: counted against the plan's processing allowance, and paid from the balance per run past it (overageCredits) · freeone of per_item · process_quota · free |
| creditsPerUsd | integer (int64) | AI ops: credits per US dollar |
| defaultModel | ImageModelPrice | AI ops: the default model's published price, as GET /api/pricing/image-models lists it |
| exactPrice | string | How to learn the exact price of one request before spending it |
| markup | number (double) | AI ops: price = providerPrice × (1 + markup) |
| overageCredits | object | Deterministic ops: credits per run past processLimit, paid from the balance — by plan, for the plans that have a limit |
| processLimit | object | Deterministic ops: items per billing period, by plan; -1 is unlimited |
| summary | string | The same, in one sentence |