# AI3D Studio API

Public, API-key-authenticated endpoints for AI generation.

- Base URL: `https://ai3d.studio/v1`
- OpenAPI: `https://ai3d.studio/openapi.json`
- Catalog: `https://ai3d.studio/.well-known/api-catalog`

## Authentication

Present your `sk-` API key (created in the dashboard under Settings → API Keys;
API access is a plan right — see the pricing page for which plans include it)
as a Bearer token. A key whose plan does not include it, or has lapsed, answers `403` with `data.code = "plan_required"`:

```
Authorization: Bearer sk-your-key
```

The `x-api-key: sk-your-key` header is also accepted. Generation bills credits
to the key's account.

## Keys

- **Format**: `sk-` + 38 base62 characters (`sk-[A-Za-z0-9]{38}`); the last
  six are a checksum, so a mistyped or truncated key is refused before it is
  looked up. Add the pattern to your secret scanner.
- **Shown once.** The full value appears only when it is created; the
  dashboard keeps a hash and a masked preview.
- **Headers only.** Send the key in `Authorization` or `x-api-key`, never in
  a query string or a URL — those end up in access logs.
- **Rotate** from Settings → API Keys: a replacement is minted and the old key
  keeps working until you revoke it, so switch your integration first. Rotate
  on a schedule and immediately on any suspected leak.
- **Last used** is shown for every key; revoke keys you no longer use.
- **Scopes** (least privilege): `read` covers every call that only reads,
  `POST /v1/quote` included; `generate` covers the calls that start runs or
  file new creations: `POST /v1/generate`, `POST /v1/batches`, a batch's `retry` and `POST /v1/tools/convert`. Each operation names its scope in the
  OpenAPI document (`x-required-scope`), and each MCP tool in `tools/list`
  (`_meta.securitySchemes`). A call outside a key's scopes answers `403` with
  `data.code = "insufficient_scope"`.
- **Expiry**: keys expire after 90 days by default (30 days, 1 year or never
  are available at creation). A lapsed key answers `401` with
  `data.code = "key_expired"`; rotate it from the dashboard.
- **IP allow-list**: a key can be pinned to IPv4/IPv6 addresses or CIDR
  blocks; requests from elsewhere answer `403` with
  `data.code = "ip_not_allowed"`.
- **Monthly credit limit**: a key can carry its own cap on the credits it
  starts runs for in a UTC calendar month. At the cap, `POST /v1/generate`
  answers `429` with `data.code = "key_credit_limit_reached"`,
  `data.resetsAt` and `Retry-After`; the MCP tools that start runs return a
  tool error carrying the same code; nothing is charged. The cap counts what
  runs really cost: a run that fails and is refunded gives its credits back.
  A batch holds its whole quote when it is accepted, so one that would pass
  the cap is refused up front, with `data.needed`; each picture then counts
  its real cost, and nothing if it is cancelled or refused before it runs.
- **Plan**: API access is a plan right; the pricing page names the plans that
  include it, and the `plan_required` message says so too. When the plan
  lapses, requests answer `403` with `data.code = "plan_required"` until it
  is renewed; the keys themselves are kept.
- **Limits**: 60 requests per minute per key, plus the account's generation
  limits; `429` responses carry `Retry-After`.
- **Failed authentication is limited separately**, and more tightly, by client
  address: repeated rejected credentials answer `429` with
  `data.code = "too_many_attempts"` before the key is even looked up. A
  successful request never counts against this budget, so a working integration
  cannot reach it — but a client that retries a revoked or mistyped key in a
  loop will, and should read `Retry-After` rather than spin.

## Endpoints

- `GET /v1/health` — liveness (no auth).
- `GET /v1/me` — your account id + credit balance.
- `GET /v1/capabilities` — models/tools available to your app, with input shapes, and the image presets (`generation.presets`).
  The form shape is versioned: send `form-contract: 4` to pin the
  versions you read (the response says which it served). A version scheduled
  to go carries `Deprecation` and `Sunset` headers; without the header you
  get the default version, which moves on only after its sunset.
- `POST /v1/quote` — what `POST /v1/generate` would charge for the same body:
  `data.credits`, `creditsPerOutput` and `outputs`. Nothing is charged. A body
  generate would refuse is refused here with the same `data.code`.
- `POST /v1/generate` — start a generation; returns a workflow id to poll. Send the
  quoted `credits` as `expectedCredits`: if the price moved since, the run is
  refused with `409`, `data.code = "price_changed"` and the new `data.credits`,
  and nothing is charged.
- `GET /v1/workflows/{id}` — poll a generation's status and result.
- `POST /v1/batches` — one run per Library picture (`items[].assetId`), for
  the scenes in `generation.batches`; returns a batch id to poll.
- `GET /v1/batches?scene=` — your batches of a scene from the last day, and how many pictures your plan lets one hold.
- `GET /v1/batches/{id}` — a batch's progress; each started item names its `workflowId`.
- `POST /v1/batches/{id}/retry` — run the failed pictures again (`itemIds` to pick).
- `POST /v1/tools/convert` — convert, compress or resize a Library GLB to GLB, STL, 3MF, OBJ or PLY on the
  server, filed back in the Library; free, answered in the same request.

## Example

```bash
# Discover what you can generate
curl -H "Authorization: Bearer sk-your-key" https://ai3d.studio/v1/capabilities

# Price it first (same body as generate, nothing is charged)
curl -X POST https://ai3d.studio/v1/quote \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"mediaType":"3d","model":"...","prompt":"...","options":{}}'

# Start a generation (body shape depends on the model — see /capabilities)
# Idempotency-Key is required: reuse it on retries to avoid double billing.
# expectedCredits is the quote's data.credits: a moved price answers 409.
curl -X POST https://ai3d.studio/v1/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mediaType":"3d","model":"...","prompt":"...","options":{},"expectedCredits":0}'

# Poll the workflow
curl -H "Authorization: Bearer sk-your-key" https://ai3d.studio/v1/workflows/WORKFLOW_ID


# Batch: one run per Library picture (scenes and models: generation.batches)
curl -X POST https://ai3d.studio/v1/batches \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"...","scene":"...","options":{},"items":[{"assetId":"..."},{"assetId":"..."}]}'
curl -H "Authorization: Bearer sk-your-key" https://ai3d.studio/v1/batches/BATCH_ID
```
