---
title: Ops
url: https://base_url.placeholder/docs/api/ops
group: Surfaces
---

# 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](https://base_url.placeholder/docs/api#conventions), and what they are for — with the calls for every SDK, the CLI and MCP — on [Ops & models](https://base_url.placeholder/docs/ops). `*` marks a required field.

- GET /api/v1/ops — List every atomic op with its parameter contract
- GET /api/v1/ops/{op} — One op's contract

## List every atomic op with its parameter contract

GET /api/v1/ops

[No API key needed](https://base_url.placeholder/docs/errors#auth)

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, description
- `pricing` — the price as data: `basis` (`per_item` · `process_quota` · `free`); for an AI op, `defaultModel` is that model's published price (the record `GET /api/pricing/image-models` publishes) with `markup` and `creditsPerUsd`; for a deterministic op, `processLimit` is the allowance per billing period by plan (-1 unlimited)
- `example` — one complete, validated `POST /api/v1/jobs` body with a placeholder asset id: copy it, swap the id. Absent for a sync op, which is not a job
- `modelCategory` — AI ops: the category a `model` must carry (`GET /api/v1/ai-models` → `categories`) to run the op
- `typicalSeconds` — how long one item usually takes as a job on the default model: a measured hint for sizing `wait`, not a promise; absent where nobody has measured
- `syncEndpoint` — 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}

[No API key needed](https://base_url.placeholder/docs/errors#auth)

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* | 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 | `not_found` — no such op; the message lists the ones there are |

## 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 string<br>e.g. "0.0024" |
| priceRange | string | Our price per image, or its range, written for a person<br>e.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 job<br>one 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 call<br>e.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 produce<br>one 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`) · `free`<br>one 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 |