Studio Media API
The /api/studio/v1 surface — catalog, jobs, media, voices, audio, health, and the shared envelope.
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:
{ "ok": true, "data": {}, "apiVersion": "v1", "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 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.
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.