The Ochra API

A REST API over HTTPS that answers JSON, at https://www.ochra.io/api/v1. It runs the same tools as the website, on the same models, at the same prices, and what it makes lands in your library beside everything you make on the site.

It is for your own servers and scripts: a shop that makes product shots, a backend that turns a brief into a video, a nightly job. To use Ochra from an AI app such as Claude, add the Ochra connector in that app instead; it needs no key.

Send the key on every request, in the Authorization header. Keys look like och_live_xxxxxxxx…; the samples below read yours from an environment variable, OCHRA_API_KEY.

Authorization: Bearer och_live_xxxxxxxx…

Call the API from your server only. A key in a web page or an app is a key anyone can copy, so the API sends no CORS headers, and a request that carries an Origin header, as a browser's does, is refused with 403. Never put a key in a URL, and revoke one you think has leaked: it stops on the next request.

Check the key: GET /me answers who the key acts as, your balance and its limits. It costs no credits.

curl https://www.ochra.io/api/v1/me \
  -H "Authorization: Bearer $OCHRA_API_KEY"

Price an image before you make it: the same request with ?price_only=true answers what it would cost and whether your balance covers it, and holds nothing.

curl -X POST "https://www.ochra.io/api/v1/images?price_only=true" \
  -H "Authorization: Bearer $OCHRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prompt": "A lighthouse on a cliff at dawn, soft film photograph", "count": 1}'

{
  "tool_name": "by_prompt",
  "total": 3,
  "balance": 1240,
  "affordable": true,
  "shortfall": 0,
  …
}

Then make it. The credits are held and the task comes back at once, with 202.

curl -X POST https://www.ochra.io/api/v1/images \
  -H "Authorization: Bearer $OCHRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prompt": "A lighthouse on a cliff at dawn, soft film photograph", "count": 1}'

curl https://www.ochra.io/api/v1/tasks/TASK_ID \
  -H "Authorization: Bearer $OCHRA_API_KEY"

The same loop in JavaScript, with fetch, from a server:

// On your server (Node 18 or later) — never in a web page.
import { randomUUID } from 'node:crypto';

const API = 'https://www.ochra.io/api/v1';
const auth = { Authorization: `Bearer ${process.env.OCHRA_API_KEY}` };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function call(path, init = {}) {
  for (;;) {
    const response = await fetch(`${API}${path}`, { ...init, headers: { ...auth, ...init.headers } });
    const body = await response.json();
    // 429: a window is full and nothing was run. Wait as long as it says, then send the same request
    // again (a generation keeps its Idempotency-Key, so it is never made twice).
    if (response.status === 429) {
      await sleep(Number(response.headers.get('Retry-After') ?? 5) * 1000);
      continue;
    }
    if (!response.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.request_id})`);
    return body;
  }
}

// 1. Start it. The credits are held and the task comes back at once (202).
let task = await call('/images', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Idempotency-Key': randomUUID() },
  body: JSON.stringify({ prompt: 'A lighthouse on a cliff at dawn, soft film photograph', count: 1 }),
});

// 2. Poll until the task is finished: every 5 seconds at first, then every 15 (a video takes minutes).
//    Every poll is a request, counted against the key's 60 a minute and 2,000 a day.
const finished = ['completed', 'partial', 'failed', 'cancelled', 'held_for_review'];
let wait = 5000;
while (!finished.includes(task.status)) {
  await sleep(wait);
  wait = Math.min(wait * 2, 15000);
  task = await call(`/tasks/${task.id}`);
}

// 3. The files are in `outputs`; each `url` is signed and expires, so download it soon.
for (const output of task.outputs) console.log(output.kind, output.url);

Every request that starts a generation, and every change to a project, needs an Idempotency-Key header: a UUID you make, new for each new request. If the answer is lost, send the same request again with the same key: you get the first task back (200, with Idempotency-Replayed: true) and are not charged twice.

A key you already used, sent with a different request, is refused with 409 conflict and charges nothing. A request refused before anything was held — a wrong field, too few credits — makes no task, so the same key can be sent again once you have fixed it.

Generation takes time, so it is a task. The request is checked and priced, the credits are held, and the answer is 202 with the task while it renders. Images usually take 10–60 seconds and videos 1–6 minutes.

{
  "id": "8f0c6a52-0000-4000-8000-000000000001",
  "status": "processing",
  "tool_name": "by_prompt",
  "progress": { "total": 1, "done": 0, "failed": 0 },
  "outputs": [],
  …
}

Poll GET /tasks/{id} every 5 seconds or so, and every 15 for a video, until status is completed, partial, failed, cancelled or held_for_review. Every poll is a request, counted against the key's 60 a minute and 2,000 a day; to follow several tasks, read them together with GET /tasks/batch. A 429 means wait the Retry-After seconds and carry on: nothing was lost.

The files are in outputs, each with a signed url that expires, so download what you keep. You are charged only for what was delivered; anything that failed is refunded by itself.

Every error is the same JSON: an HTTP status, error.code, a sentence you can show, and sometimes meta with the details. Every answer carries X-Request-Id; include it when you write to us.

{
  "status_code": 402,
  "detail": "This request needs 29 credits, but this key has 4 of its 30-day limit of 1000 credits left (996 used). Raise the limit in Settings → API keys.",
  "error": {
    "code": "key_cap_reached",
    "message": "This request needs 29 credits, but this key has 4 of its 30-day limit of 1000 credits left (996 used). Raise the limit in Settings → API keys.",
    "meta": { "reason": "key_cap_reached", "cap_credits": 1000, "spent_credits": 996, "required_credits": 29 }
  },
  "request_id": "6f1c2a9e-0000-4000-8000-000000000002"
}

• 400 bad_request

  The request could not be read: a generation or project change sent without an Idempotency-Key header, or with one that is not a UUID, or a body that is not valid JSON. Nothing was run.

• 401 unauthenticated

  No key, a key that is not recognised, or a revoked key. Check the Authorization header.

• 402 insufficient_credits

  Your balance cannot cover this request. Nothing was held; top up and send it again.

• 402 key_cap_reached

  This request would take the key past its cap. meta.required_credits is what the request needs, meta.cap_credits the cap and meta.spent_credits what the key has used in the last 30 days. Send a smaller request, raise the cap in Settings → API keys, or use another key.

• 403 forbidden · meta.reason: browser_origin

  The request carried an Origin header, as one from a web page does. Call the API from your server; never put a key in a web page.

• 403 forbidden · meta.reason: scope

  The key has Read access and the request would generate or change something.

• 403 forbidden · meta.reason: kind_not_allowed / model_not_allowed

  The request is outside the limits set on the key: a kind of media or a model it may not use. meta.allowed_models lists what it may.

• 403 forbidden · meta.reason: customer_key_on_mcp

  A key was sent to the MCP endpoint. To use Ochra from an AI app, add the Ochra connector there instead.

• 404 not_found

  No such thing in your account — or it belongs to another account, which looks the same.

• 409 conflict

  The Idempotency-Key was already used for a different request. Nothing was charged; send a new key for a new request.

• 422 validation_error

  A field is missing or wrong. error.details names each field and what to change.

• 429 rate_limited

  Too many requests in one of the windows below. Wait the Retry-After seconds, then retry; nothing was run.

• 500 internal_error

  Something failed on our side. Retry later; if it keeps happening, send us the request_id.

• 503 maintenance

  The site has reached its generation limit for the day, or is briefly down for maintenance. Nothing was charged. Try again after Retry-After seconds; the daily limit resets at 00:00 UTC.

Every answer to a request with a key carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for the window nearest to refusing you. A refused request is a 429 rate_limited with Retry-After in seconds, and spends nothing.

• 60 per minute · 2,000 per day

  Per API key

  Every authenticated request, per API key.

• 10 per minute

  Per API key

  Requests that create a generation task (POST /generations, /images, /videos, /photoshoots and the character endpoints), per API key.

• 300 per day

  Per account (all its keys together)

  Requests that create a generation task the account has the credits for, counted across every API key of one account together.

• 600 per hour

  Per deployment (all customer keys together)

  Requests that create a generation task the account has the credits for, counted across every customer’s API keys together.

• 30 per hour

  Per API key

  POST /assets/import (the server downloads a URL), per API key, whether or not the import succeeds.

• 30 per 5 minutes

  Per client network (hashed; IPv6 by /64)

  Failed authentications that reach the key table (an unknown or revoked key, or an owner who may not use it), per client network: the IPv4 address, or the /64 of an IPv6 one. A missing or malformed key is refused without being counted.

Paths are under https://www.ochra.io/api/v1. Marked ones need a key with Read and generateaccess, and an Idempotency-Key where noted.

Every endpoint, field and error above, as an OpenAPI 3.1 document your tools can read — generated from the same contract the API checks requests with, so it is never behind it. It needs no key; with your key it describes exactly what that key may call. Send its ETag back as If-None-Match and an unchanged document answers 304.

https://www.ochra.io/api/v1/openapi.json