# Studio Media API

The Studio Media API (`/api/studio/v1`, served from `studio.upcube.ai`) is the programmatic surface behind the workbench. All responses are `no-store`; every response carries an `X-Studio-Api-Version` header.

## Envelope

Success and failure share one envelope:

```json
{ "ok": true, "data": {}, "apiVersion": "v1", "requestId": "..." }
```

```json
{ "ok": false, "error": { "code": "VALIDATION_ERROR", "message": "...", "requestId": "..." } }
```

Mutations accept an `idempotency-key` header. List endpoints paginate with `limit` (1–100), `cursor`, `sort` (`created_at` or `updated_at`), and `direction` (`asc` or `desc`).

## Health

`GET /api/studio/v1/health` is the public liveness probe: `{ ok: true, app: "@ethen/studio", release: "v1" }`. Liveness only — it proves web availability without secrets, database, or provider work.

## Catalog

`GET /api/studio/v1/catalog` browses the endpoint catalog, optionally filtered by `?task=<task-name>`. Unknown task names fail with `VALIDATION_ERROR`. Without a project scope, the public lane serves the checked-in generated registry (release metadata, no user data) with no session required. A fetch failure is an error, never an empty catalog.

Related: `catalog/resolve`, `catalog/[endpointId]`, `catalog/preferences`.

## Jobs

`GET /api/studio/v1/jobs` lists jobs; `POST` admits a new job (validate → quote → admit). `GET /api/studio/v1/jobs/[jobId]` reads one job; `POST .../cancel` cancels a running attempt. See [Jobs](/docs/studio/jobs) for the lifecycle.

## Media

- `POST /api/studio/v1/media/ingest` — ingest source media; `GET .../ingest/[processId]` tracks the ingest.
- `GET /api/studio/v1/media/exports`, `POST` — list and create exports; `GET .../exports/[exportId]` reads one.
- `GET /api/studio/v1/media/downloads` — download finished media.

## Voices and audio

- `POST /api/studio/v1/voices/clone` — design or clone a voice identity (consent evidence required for clones).
- `GET|POST /api/studio/v1/voices/bindings` — list or attach provider bindings.
- `/api/studio/v1/audio/projects` — audio projects with stages and transcripts.

See [Voices](/docs/studio/voices).

## Auth

Reads of public release metadata need no session. Everything project-scoped requires a signed-in session plus project scope; unauthenticated calls fail closed. Studio setup gates the workbench until prerequisites complete.

## Next steps

- [Jobs](/docs/studio/jobs)
- [Voices](/docs/studio/voices)
- [Troubleshooting](/docs/resources/troubleshooting)