# AITOPIA REST API

> HTTP API to run AITOPIA image, video and audio models, edit existing media and submit batches, server-to-server with a developer key. Base URL: https://api-live.aitopia.ai (live; every path starts with /v1). Sandbox: https://api-sandbox.aitopia.ai with test keys (aitk_test_...): same requests and validation, simulated results, nothing charged. Credits are spent from the account that owns the key.

- Auth: `Authorization: Key aitk_live_...` (`Bearer` also accepted); test keys `aitk_test_...` work only on the sandbox host, live keys only on the live host. Keys are created on aitopia.ai under profile menu > API keys.
- Sandbox outcomes: send `X-Sandbox-Outcome: completed|failed|partial` on a sandbox submit to test error handling.
- Async: submit (`POST /v1/models/{model_id}`, `POST /v1/edit`, `POST /v1/batch`) answers 202 with `request_id`, `status_url`, `cancel_url`; poll `GET /v1/requests/{request_id}?wait=N` (N 0-60) or pass `webhook_url`.
- Final statuses: `completed`, `partial`, `failed`, `cancelled`. Files are in `output.images[]`, `output.videos[]`, `output.audio[]`, `output.files[]`.
- Models: `GET /v1/models` (filter `type`, `q`; page with `limit`, `offset`), input schema and price: `GET /v1/models/{model_id}`. Model ids contain "/" (send it as is or as %2F), for example google/nano-banana-2 (image), minimax/h3-max (video), minimax/speech-2.8-hd (speech).
- Price only: add `?dry_run=true` to a submit call. Errors: `{ "error": { "code", "message", "retryable", "field"?, "retry_after_seconds"? } }`.
- Webhooks are signed: `X-AITOPIA-Signature: t=<unix>,v1=<hex HMAC-SHA256(webhook_secret, "<t>.<raw body>")>`.
- Submits are not idempotent; results are kept 30 days.

## Get started

- [Overview](index.md): Generate images, videos and audio from your own application with one API key.
- [Quickstart](quickstart/index.md): Create a key, find a model, submit a run, poll it and read the result.
- [Authentication](authentication/index.md): Send your developer key with every request; what each 401 means.
- [Sandbox](sandbox/index.md): Build and test your integration for free with test keys; runs are simulated and nothing is charged.

## How the API works

- [Requests & lifecycle](guides/requests/index.md): Submit, follow and cancel requests; statuses and the result object.
- [Polling](guides/polling/index.md): Follow a request with GET /v1/requests/{request_id}, optionally long-polling with ?wait.
- [Webhooks](guides/webhooks/index.md): Receive the final result as a signed POST instead of polling.
- [File uploads](guides/uploads/index.md): Host your own images, videos and audio on AITOPIA to use them as model or edit input.
- [Errors & retries](guides/errors/index.md): The error body, every error code with its HTTP status, and when to retry.
- [Rate limits](guides/rate-limits/index.md): Per-key, per-account and per-IP limits, the rate limit headers and other usage limits.
- [Billing & retention](guides/billing/index.md): Who pays, price estimates and dry runs, per-key credit caps, and how long results are kept.

## Endpoints reference

- [All endpoints](reference/index.md): Every endpoint of the AITOPIA REST API.
- [Models](reference/models/index.md): List models and read one model's input schema and price.
- [Runs](reference/runs/index.md): Submit model runs, edits and batches.
- [Requests](reference/requests/index.md): Read the status and result of a request, or cancel it.
- [Uploads](reference/uploads/index.md): Host files on AITOPIA to use them as model or edit input.
- [Account](reference/account/index.md): Credit balance of the key owner.
- [OpenAPI document](reference/openapi/index.md): The machine-readable description of the API.
- [Schemas](reference/schemas/index.md): Objects shared by several endpoints.

## Optional

- [OpenAPI 3.1 document](openapi.json): every endpoint, parameter and schema