{ "openapi": "3.1.0", "info": { "title": "VoiceStudio Cloud Public API", "version": "1.0.0", "description": "The versioned public developer contract for VoiceStudio Cloud. The service is not released; this reference has no active server and its examples are non-executable until release verification passes." }, "servers": [], "tags": [ { "name": "Artifacts" }, { "name": "Jobs" }, { "name": "Usage" }, { "name": "Voices" }, { "name": "Dubbing" }, { "name": "Audio" }, { "name": "Audiobooks" }, { "name": "Projects" }, { "name": "Models" }, { "name": "Text resources" } ], "paths": { "/v1/artifacts/upload-authorizations": { "post": { "operationId": "authorizeArtifactUpload", "tags": [ "Artifacts" ], "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadAuthorizationRequest" } } } }, "responses": { "201": { "description": "Upload authorization created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadAuthorization" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/artifacts/{artifact_id}/complete": { "post": { "operationId": "completeArtifactUpload", "tags": [ "Artifacts" ], "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/ArtifactId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteUploadRequest" } } } }, "responses": { "200": { "description": "Verified Artifact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artifact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/artifacts/{artifact_id}/download-authorization": { "post": { "operationId": "authorizeArtifactDownload", "tags": [ "Artifacts" ], "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/ArtifactId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Short-lived download authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadAuthorization" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/jobs": { "get": { "operationId": "listJobs", "tags": [ "Jobs" ], "description": "Cursor-paged, Organization-scoped Job listing in newest-first keyset order with optional exact-match state, workflow, and client_reference filters. A scoped API credential needs jobs:read, and its Organization is the one stored on the verified credential: organization_id is optional and, when supplied, must equal that Organization. Any other well-formed organization_id returns the same masked 404 as an unavailable Organization, without a Membership lookup. A Keycloak bearer caller must supply organization_id, which its current PostgreSQL Membership authorizes; a missing or foreign Membership is masked as 404. No caller-selected Organization header grants access, and browser sessions cannot reach this operation.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "required": false, "description": "Required for a Keycloak bearer caller. Optional for a scoped API credential; when supplied it must equal the credential's stored Organization. A malformed value is a 400 for either caller.", "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "running", "canceling", "succeeded", "failed", "canceled" ] } }, { "name": "workflow", "in": "query", "required": false, "description": "Exact workflow name; lowercase letters, digits, '.', '_', and '-'.", "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9._-]*$" } }, { "name": "client_reference", "in": "query", "required": false, "description": "Exact customer-supplied client reference; control characters are rejected.", "schema": { "type": "string", "maxLength": 128 } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PageLimit" } ], "responses": { "200": { "description": "One page of Jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" }, "post": { "operationId": "createJob", "tags": [ "Jobs" ], "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobRequest" } } } }, "responses": { "202": { "description": "Job and Usage Reservation committed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAdmission" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/jobs/{job_id}": { "get": { "operationId": "getJob", "tags": [ "Jobs" ], "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" } ], "responses": { "200": { "description": "Current durable Job state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/jobs/{job_id}/transcript": { "get": { "operationId": "getJobTranscript", "tags": [ "Jobs" ], "description": "Read the committed transcription.v1 output as its versioned JSON document or a server-rendered text, SRT, or VTT view. API credentials require both jobs:read and artifacts:read; Job and Artifact ownership are checked separately. Authenticated browser sessions may reach this exact route through the dashboard gateway, which forwards its server-held identity and selected Organization. Responses are never cacheable.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "text", "srt", "vtt" ], "default": "json" } } ], "responses": { "200": { "description": "Verified transcript or derived view.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptDocument" } }, "text/plain": { "schema": { "type": "string" } }, "application/x-subrip": { "schema": { "type": "string" } }, "text/vtt": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/jobs/{job_id}/cancel": { "post": { "operationId": "cancelJob", "tags": [ "Jobs" ], "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Cancellation is durable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAdmission" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/jobs/{job_id}/events": { "get": { "operationId": "streamJobEvents", "tags": [ "Jobs" ], "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "name": "Last-Event-ID", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "200": { "description": "Resumable Server-Sent Events stream.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/usage": { "get": { "operationId": "getUsageSummary", "tags": [ "Usage" ], "description": "Read-only ledger-derived Organization usage summary, semantically identical to the dashboard usage projection. Responses are Cache-Control no-store. An unknown or foreign organization is indistinguishable from a missing one.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/UsageOrganization" } ], "responses": { "200": { "description": "Organization usage summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/usage/events": { "get": { "operationId": "listUsageEvents", "tags": [ "Usage" ], "description": "Cursor-paged, append-only settled usage events, newest first. Settlements and compensating Credit entries are immutable and typed as what they are. Cursors are opaque and stable across pages.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/UsageOrganization" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/UsagePageLimit" } ], "responses": { "200": { "description": "One page of settled usage events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEventList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/usage/breakdown": { "get": { "operationId": "getUsageBreakdown", "tags": [ "Usage" ], "description": "Bounded aggregation of settled usage grouped by day, project, or workflow over a server-bounded window (92 days maximum; oversized windows are clamped and the effective window echoed). The credential dimension is reserved vocabulary and fails with the stable error code unsupported_dimension until credential attribution is recorded on Jobs.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/UsageOrganization" }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "day", "project", "workflow", "credential" ], "default": "day" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Aggregated settled usage groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBreakdown" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/voices": { "get": { "operationId": "listVoices", "tags": [ "Voices" ], "description": "Cursor-paged Voice library listing. source=catalog is a global read that ignores project_id. The default source=customer listing requires project_id as the tenant-selection handle: omitting it, or sending an empty or over-128-character value, returns 400 invalid_request before any tenant read, as does an unknown source. A bearer principal proves current PostgreSQL Membership on that Project; a scoped API credential (voices:read) checks the Project inside its stored Organization; an unavailable or foreign Project is masked as 404. No caller-selected Organization header grants access.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Required unless source=catalog. The Project whose Organization's customer Voices are listed.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "source", "in": "query", "required": false, "description": "Defaults to customer.", "schema": { "type": "string", "enum": [ "customer", "catalog" ], "default": "customer" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PageLimit" } ], "responses": { "200": { "description": "One page of Voices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" }, "post": { "operationId": "createVoice", "tags": [ "Voices" ], "description": "Records exactly one supported Voice provenance: a consent-backed ready reference_audio Artifact, an approved catalog Voice, or a succeeded voice_design_preview Job with one verified WAV output. For a reference recording, the consent principal is always the authenticated caller; a request can never attest on behalf of someone else.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/VoiceIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCreateRequest" } } } }, "responses": { "201": { "description": "Voice recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/voices/design-previews": { "post": { "operationId": "createVoiceDesignPreview", "tags": [ "Voices" ], "description": "Admits a durable, billed voice_design_preview Job from a bounded, reviewed OmniVoice design taxonomy, an approved model, and a server-owned preview phrase. Unsupported prose and conflicting attributes are rejected before staging or billing. The resulting verified WAV may be saved exactly once through POST /v1/voices using design_preview_job_id.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/VoiceIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceDesignPreviewRequest" } } } }, "responses": { "202": { "description": "Voice design preview Job committed for dispatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/voices/{voice_id}": { "get": { "operationId": "getVoice", "tags": [ "Voices" ], "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/VoiceId" } ], "responses": { "200": { "description": "Current Voice state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" }, "patch": { "operationId": "updateVoice", "tags": [ "Voices" ], "description": "Updates the mutable presentation fields. An omitted field is left unchanged; consent and the reference Artifact are immutable.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/VoiceId" }, { "$ref": "#/components/parameters/VoiceIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceUpdateRequest" } } } }, "responses": { "200": { "description": "Updated Voice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" }, "delete": { "operationId": "deleteVoice", "tags": [ "Voices" ], "description": "Begins Voice deletion. The idempotency digest is target-bound, so the same key cannot be replayed against a different Voice.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/VoiceId" }, { "$ref": "#/components/parameters/VoiceIdempotencyKey" } ], "responses": { "204": { "description": "Deletion accepted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/voices/{voice_id}/lock": { "post": { "operationId": "lockVoice", "tags": [ "Voices" ], "description": "Locks a ready Voice against further mutation. A Voice whose state does not allow the transition answers 409 conflict.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/VoiceId" }, { "$ref": "#/components/parameters/VoiceIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceLockRequest" } } } }, "responses": { "200": { "description": "Locked Voice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/voices/{voice_id}/clone": { "post": { "operationId": "cloneVoice", "tags": [ "Voices", "Jobs" ], "description": "Admits asynchronous processing for one consented draft Voice. Scoped API credentials require both voices:write and jobs:write. The server stages its own bounded preview phrase; the tenant-RLS transaction revalidates the draft Voice, consented reference audio, duration, model, reservation, Job, and immutable Voice-to-Job link before committing. The target Voice ID never enters the GPU task snapshot.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/VoiceId" }, { "$ref": "#/components/parameters/VoiceIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCloneRequest" } } } }, "responses": { "202": { "description": "Voice clone Job and Usage Reservation committed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAdmission" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/voices/{voice_id}/unlock": { "post": { "operationId": "unlockVoice", "tags": [ "Voices" ], "description": "Returns a locked Voice to the ready state.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/VoiceId" }, { "$ref": "#/components/parameters/VoiceIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceLockRequest" } } } }, "responses": { "200": { "description": "Unlocked Voice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/voices/{voice_id}/usage": { "get": { "operationId": "getVoiceUsage", "tags": [ "Voices" ], "description": "Bounded Voice usage projection. The Job count stops at a server bound and reports truncation rather than scanning the full Job history.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/VoiceId" } ], "responses": { "200": { "description": "Bounded usage projection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceUsage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/voices/{voice_id}/preview": { "get": { "operationId": "getVoicePreview", "tags": [ "Voices" ], "description": "Redirects to the Voice's preview audio so an audio element can play it directly; a browser element cannot issue the POST that mints an Artifact download grant. Catalog previews are public-readable platform assets and need only an authenticated principal, so no tenant scope is applied to them. A library preview belongs to one Organization and is authorized against it, and a preview belonging to another tenant is masked as absent. The redirect target is short-lived; the redirect itself is cacheable for well under that lifetime.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/VoiceId" } ], "responses": { "302": { "description": "Redirect to the preview audio.", "headers": { "Location": { "description": "Expiring URL for the preview audio.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Bounded well inside the redirect target's lifetime.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/dubbing": { "post": { "operationId": "createDubbingProject", "tags": [ "Dubbing" ], "description": "Creates a Dubbing Project over a ready source Artifact. The owning Project supplies the Organization; bearer callers prove Membership, while scoped credentials require jobs:write and artifacts:read and check that Project in their stored Organization. A Project the caller cannot use is masked as 404.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/BoundedIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DubbingCreateRequest" } } } }, "responses": { "201": { "description": "Dubbing Project created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DubbingProject" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" }, "get": { "operationId": "listDubbingProjects", "tags": [ "Dubbing" ], "description": "Cursor-paged Dubbing Project listing. project_id is required: this surface has no ambient Organization context, so the listing is scoped and authorized through the owning Project. Scoped credentials require jobs:read and check that Project inside their stored Organization.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PageLimit" } ], "responses": { "200": { "description": "One page of Dubbing Projects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DubbingProjectList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/dubbing/{dubbing_id}": { "get": { "operationId": "getDubbingProject", "tags": [ "Dubbing" ], "description": "Scoped credentials require jobs:read and exact Dubbing Project ownership.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/DubbingId" } ], "responses": { "200": { "description": "Dubbing Project with its per-language stage states.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DubbingProject" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" }, "delete": { "operationId": "deleteDubbingProject", "tags": [ "Dubbing" ], "description": "Deletes the Dubbing Project. The idempotency digest is bound to the target so the same key cannot be replayed against another project. Scoped credentials require jobs:write and exact object ownership.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/DubbingId" }, { "$ref": "#/components/parameters/BoundedIdempotencyKey" } ], "responses": { "204": { "description": "Dubbing Project deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/dubbing/{dubbing_id}/stages/{stage}": { "post": { "operationId": "admitDubbingStage", "tags": [ "Dubbing" ], "description": "Admits one pipeline stage for the named target languages, or for every track when languages is omitted. A stage cannot be admitted before its predecessor succeeds, which answers 409 stage_order. Synthesis accepts exactly one language and an immutable approved model; its atomic prepared-plan admission and private CUDA runtime capability are enabled. Transcription's dormant audio contract targets every track with no languages field and requires an immutable approved ASR model plus mode fast or accurate. Translation's dormant contract accepts exactly one language, an immutable approved model, and quality fast, cinematic, or autofit. Transcribe, translate, and mux answer 503 workflow_unavailable until their runtime gates pass. Scoped credentials require jobs:write and artifacts:read plus exact Dubbing Project ownership.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/DubbingId" }, { "name": "stage", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "transcribe", "translate", "synthesize", "mux" ] } }, { "$ref": "#/components/parameters/BoundedIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DubbingStageAdmitRequest" } } } }, "responses": { "202": { "description": "Stage admission is durable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DubbingProject" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/dubbing/{dubbing_id}/segments": { "get": { "operationId": "listDubbingSegments", "tags": [ "Dubbing" ], "description": "Cursor-paged source segments. Supplying lang additionally returns that track's translation, synthesis state, and reprocess flag per segment. Scoped credentials require jobs:read and artifacts:read and exact Dubbing Project ownership.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/DubbingId" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 32 } }, { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } } ], "responses": { "200": { "description": "One page of dubbing segments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DubbingSegmentList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" }, "patch": { "operationId": "editDubbingSegments", "tags": [ "Dubbing" ], "description": "Bounded batch edit of source segments and their per-language translations. Only counts are returned, so the result is safe to store as audit metadata and as an idempotency replay record. Scoped credentials require jobs:write and exact Dubbing Project ownership.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/DubbingId" }, { "$ref": "#/components/parameters/BoundedIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DubbingSegmentsEditRequest" } } } }, "responses": { "200": { "description": "Edit counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DubbingSegmentsEditResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/audio/transcriptions": { "post": { "operationId": "createTranscription", "tags": [ "Audio" ], "description": "OpenAI-compatible transcription. The upload is bounded at 25 MiB and must be audio/wav, audio/mpeg, audio/flac, or audio/ogg. The request waits for a terminal Job and returns the transcript projected into the requested response_format; past the wait deadline it returns 202 with the job_id and the client continues through the standard Job and Artifact APIs. X-Job-Id is always set once admission succeeds. Failures use the OpenAI-compatible error envelope, not the platform ErrorEnvelope. prompt and temperature are accepted, bounded, and ignored, and stay out of the idempotency digest. project_id is optional only where server-side default Project resolution is wired and the principal's Membership is unambiguous; a caller in several Organizations must send it (project_ambiguous, project_required, default_project_not_found).", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TranscriptionRequest" } } } }, "responses": { "200": { "description": "Completed transcript, projected into the requested response_format.", "headers": { "X-Job-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcription" } }, "text/plain": { "schema": { "type": "string" } }, "application/x-subrip": { "schema": { "type": "string" } }, "text/vtt": { "schema": { "type": "string" } } } }, "202": { "description": "The Job did not reach a terminal state before the wait deadline, or succeeded without a readable transcript Artifact. Recover through GET /v1/jobs/{job_id} and the Artifact download authorization.", "headers": { "X-Job-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatJobAccepted" } } } }, "400": { "$ref": "#/components/responses/CompatBadRequest" }, "401": { "$ref": "#/components/responses/CompatUnauthorized" }, "404": { "$ref": "#/components/responses/CompatNotFound" }, "409": { "$ref": "#/components/responses/CompatConflict" }, "413": { "$ref": "#/components/responses/CompatPayloadTooLarge" }, "429": { "$ref": "#/components/responses/CompatRateLimited" }, "500": { "$ref": "#/components/responses/CompatServerError" }, "503": { "$ref": "#/components/responses/CompatUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/audiobooks/plan": { "post": { "operationId": "planAudiobook", "tags": [ "Audiobooks" ], "description": "Synchronous, GPU-free audiobook planning. It admits no Job: it reads a ready script Artifact, computes the versioned plan, and optionally stores it as an audiobook_plan Artifact. The body carries references and options only, never script text, and the plan itself carries codepoint offsets rather than script content. store_plan creates a tenant Artifact and therefore additionally requires the Artifact-management role, which is the only 403 on this route. Render admission is deliberately not open.", "security": [ { "DeveloperCredential": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudiobookPlanRequest" } } } }, "responses": { "200": { "description": "Computed audiobook plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudiobookPlanResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/projects": { "get": { "operationId": "listProjects", "tags": [ "Projects" ], "description": "Lists safe Project metadata inside the verified API credential's stored Organization. Requires projects:read. Browser and Keycloak bearer principals are not accepted on this machine-only route.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PageLimit" } ], "responses": { "200": { "description": "Stable page of Projects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" }, "post": { "operationId": "createProject", "tags": [ "Projects" ], "description": "Creates a Project inside the verified API credential's stored Organization. Requires projects:write. The Organization is never a request field.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "Maximum encoded request body is 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } } }, "responses": { "201": { "description": "Durable Project creation result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/models": { "get": { "operationId": "listModels", "tags": [ "Models" ], "description": "Lists at most 100 active, explicitly reviewed model versions for the requested workflow. This machine-principal route requires jobs:read; its Organization comes only from the verified API credential. The projection never contains digests, raw parameter schemas, runtime or node topology, capacity, storage sources, policy identifiers, or geographic policy. Region-restricted entries remain unpublished until the platform has an explicit approved_regions authority contract.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "name": "workflow", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "tts", "transcription" ] } } ], "responses": { "200": { "description": "Deterministically ordered reviewed model versions.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PublicTTSModelList" }, { "$ref": "#/components/schemas/PublicTranscriptionModelList" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/projects/{project_id}": { "get": { "operationId": "getProject", "tags": [ "Projects" ], "description": "Reads safe metadata for one Project in the verified credential's stored Organization. Requires projects:read; absent and foreign identifiers are indistinguishable.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Project metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" }, "patch": { "operationId": "patchProject", "tags": [ "Projects" ], "description": "Changes only the slug and display name of one Project in the verified credential's stored Organization. Requires projects:write.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "Maximum encoded request body is 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchProjectRequest" } } } }, "responses": { "200": { "description": "Durable Project update result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/projects/{project_id}/glossary": { "get": { "operationId": "getProjectGlossary", "tags": [ "Text resources" ], "description": "The full, bounded Project glossary. Project Membership is masked as 404 to avoid cross-tenant Project enumeration.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "responses": { "200": { "description": "Project glossary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Glossary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" }, "put": { "operationId": "replaceProjectGlossary", "tags": [ "Text resources" ], "description": "Full replacement is deliberately the only glossary mutation: it keeps ordering, deduplication, and idempotent replay simple and sufficient. Terms are unique on the language and term pair.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/BoundedIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlossaryReplaceRequest" } } } }, "responses": { "200": { "description": "Replaced Project glossary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Glossary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/pronunciation": { "get": { "operationId": "listPronunciationEntries", "tags": [ "Text resources" ], "description": "Cursor-paged Organization pronunciation lexicon. organization_id is required and is never an authorization input on its own: Membership in it is proven per request, and a missing Membership is indistinguishable from an absent Organization.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/PronunciationOrganization" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PageLimit" } ], "responses": { "200": { "description": "One page of pronunciation entries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PronunciationEntryList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" }, "post": { "operationId": "createPronunciationEntry", "tags": [ "Text resources" ], "description": "Creates one entry. Exactly one of phoneme or alias must be present. A second entry for the same grapheme answers 409 conflict.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/BoundedIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PronunciationEntryRequest" } } } }, "responses": { "201": { "description": "Pronunciation entry created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PronunciationEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } }, "/v1/pronunciation/{entry_id}": { "put": { "operationId": "updatePronunciationEntry", "tags": [ "Text resources" ], "description": "Replaces the entry's writable fields. The idempotency digest binds the key to this exact entry and body, so a reused key cannot silently target another entry.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/PronunciationEntryId" }, { "$ref": "#/components/parameters/BoundedIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PronunciationEntryRequest" } } } }, "responses": { "200": { "description": "Updated pronunciation entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PronunciationEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" }, "delete": { "operationId": "deletePronunciationEntry", "tags": [ "Text resources" ], "description": "Deletes the entry. There is no body; the stable, target-bound digest prevents the same key from being replayed against another entry.", "security": [ { "DeveloperCredential": [] } ], "parameters": [ { "$ref": "#/components/parameters/PronunciationEntryId" }, { "$ref": "#/components/parameters/PronunciationOrganization" }, { "$ref": "#/components/parameters/BoundedIdempotencyKey" } ], "responses": { "204": { "description": "Pronunciation entry deleted." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/DependencyUnavailable" } }, "x-voicestudio-audience": "public-developer" } } }, "components": { "parameters": { "ArtifactId": { "name": "artifact_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, "BoundedIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Replay key bounded at 128 characters by the dubbing and lexicon surfaces. Reusing a key with a different request body is a 409 idempotency_conflict.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 } }, "DubbingId": { "name": "dubbing_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128 } }, "JobId": { "name": "job_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, "PageLimit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "ProjectId": { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, "PronunciationEntryId": { "name": "entry_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, "PronunciationOrganization": { "name": "organization_id", "in": "query", "required": true, "description": "Organization whose pronunciation lexicon is addressed. Membership in it is proven per request; the identifier alone never selects a tenant.", "schema": { "$ref": "#/components/schemas/OpaqueId" } }, "UsageOrganization": { "name": "organization", "in": "query", "required": false, "description": "Organization to read. Optional for callers with exactly one active Membership; required (organization_required) when membership is ambiguous. Never an authorization input on its own.", "schema": { "$ref": "#/components/schemas/OpaqueId" } }, "UsagePageLimit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "VoiceId": { "name": "voice_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, "VoiceIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Replay key for the Voice surface, which bounds keys at 512 characters rather than the 128 used elsewhere.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } } }, "responses": { "BadRequest": { "description": "Invalid request syntax.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "CompatBadRequest": { "description": "Invalid request (invalid_request, unsupported_media_type, unsupported_parameter, invalid_duration, project_required, project_ambiguous).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } } }, "CompatConflict": { "description": "The Job was canceled before it produced output (job_canceled), or a replayed Idempotency-Key does not match its original request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } } }, "CompatNotFound": { "description": "The model or the Project is not available (model_not_found, project_not_found, default_project_not_found). A foreign resource is masked identically to an absent one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } } }, "CompatPayloadTooLarge": { "description": "The uploaded file exceeds the 25 MiB bound (file_too_large).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } } }, "CompatRateLimited": { "description": "Too many concurrent synchronous requests (concurrency_limit_exceeded), or a metering or admission limit was exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } } }, "CompatServerError": { "description": "The Job failed before it produced output (job_failed), or the request could not be processed (internal_error).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } } }, "CompatUnauthorized": { "description": "Authentication required or invalid (unauthenticated).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } } }, "CompatUnavailable": { "description": "Upload ingestion, authentication, or the workflow is temporarily unavailable (dependency_unavailable, authentication_unavailable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } } }, "Conflict": { "description": "Idempotency or state conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "DependencyUnavailable": { "description": "A durable dependency is temporarily unavailable, or the requested workflow has no enabled registry entry (workflow_unavailable). Retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Forbidden": { "description": "Caller is not authorized for the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotFound": { "description": "Resource not found or not visible to this tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "Rate or compute admission limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unauthorized": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unprocessable": { "description": "Valid syntax but unsupported model or configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "UnsupportedMediaType": { "description": "The document type cannot be converted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "Artifact": { "type": "object", "additionalProperties": false, "required": [ "id", "project_id", "purpose", "state", "media_type", "size_bytes", "sha256", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueId" }, "project_id": { "$ref": "#/components/schemas/OpaqueId" }, "purpose": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "quarantined", "ready", "deleting", "deleted", "rejected" ] }, "media_type": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string" }, "duration_ms": { "type": "integer", "minimum": 0 }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "AudiobookPlanRequest": { "type": "object", "additionalProperties": false, "required": [ "project_id", "script_artifact_id" ], "properties": { "project_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "script_artifact_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "model_class": { "type": "string", "enum": [ "", "standard", "fast" ] }, "chapterization": { "type": "object", "additionalProperties": false, "properties": { "mode": { "type": "string", "enum": [ "", "headings", "fixed" ], "description": "headings splits at Markdown ATX headings; fixed packs paragraph spans up to the per-chapter bound." }, "max_chapter_codepoints": { "type": "integer", "description": "Zero selects the server default. A non-zero value must fall between 1000 and 200000." } } }, "voices": { "type": "object", "additionalProperties": false, "properties": { "default_voice_id": { "type": "string", "maxLength": 128 }, "assignments": { "type": "object", "description": "Chapter index, as a decimal string key, mapped onto a voice identifier. At most 200 entries and every index below 200.", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 128 } } } }, "store_plan": { "type": "boolean", "description": "Stores the plan as an audiobook_plan Artifact. This creates a tenant Artifact and additionally requires the Artifact-management role." } } }, "AudiobookPlanResponse": { "type": "object", "additionalProperties": false, "required": [ "plan" ], "properties": { "plan": { "$ref": "#/components/schemas/AudiobookPlan" }, "plan_artifact_id": { "type": "string", "maxLength": 128, "description": "Present only when store_plan was requested and succeeded." } } }, "AudiobookPlan": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "script_artifact_id", "model_class", "rating_policy_version", "options", "chapters", "total_codepoints", "estimated_credit_units" ], "description": "estimated_credit_units is in integer milli-credits under rating_policy_version and equals the sum of the chapter estimates.", "properties": { "schema_version": { "type": "string" }, "script_artifact_id": { "type": "string", "maxLength": 128 }, "script_artifact_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "model_class": { "type": "string" }, "rating_policy_version": { "type": "string" }, "options": { "type": "object", "additionalProperties": false, "required": [ "mode", "max_chapter_codepoints" ], "properties": { "mode": { "type": "string", "enum": [ "headings", "fixed" ] }, "max_chapter_codepoints": { "type": "integer", "minimum": 1 } } }, "chapters": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/AudiobookChapter" } }, "total_codepoints": { "type": "integer", "minimum": 0 }, "estimated_credit_units": { "type": "integer", "minimum": 0 } } }, "AudiobookChapter": { "type": "object", "additionalProperties": false, "required": [ "index", "title", "spans", "codepoints", "estimated_credit_units" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "title": { "type": "string" }, "voice_id": { "type": "string", "maxLength": 128 }, "spans": { "type": "array", "items": { "$ref": "#/components/schemas/AudiobookSpan" } }, "codepoints": { "type": "integer", "minimum": 0 }, "estimated_credit_units": { "type": "integer", "minimum": 0 } } }, "AudiobookSpan": { "type": "object", "additionalProperties": false, "required": [ "start_codepoint", "end_codepoint" ], "description": "A half-open codepoint range into the normalized script. A plan carries offsets, never script text beyond chapter titles.", "properties": { "start_codepoint": { "type": "integer", "minimum": 0 }, "end_codepoint": { "type": "integer", "minimum": 0 } } }, "CompatErrorEnvelope": { "type": "object", "additionalProperties": false, "required": [ "error" ], "description": "The OpenAI-compatible error shape. It deliberately differs from the platform ErrorEnvelope and carries no request_id.", "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "message", "type", "code" ], "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "rate_limit_error", "server_error" ] }, "code": { "type": "string" } } } } }, "CompatJobAccepted": { "type": "object", "additionalProperties": false, "required": [ "job_id" ], "properties": { "job_id": { "$ref": "#/components/schemas/OpaqueId" } } }, "CompleteUploadRequest": { "type": "object", "additionalProperties": false, "required": [ "size_bytes", "sha256" ], "properties": { "size_bytes": { "type": "integer", "minimum": 1 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "CreateJobRequest": { "type": "object", "additionalProperties": false, "required": [ "project_id", "workflow", "model", "input", "configuration" ], "properties": { "project_id": { "$ref": "#/components/schemas/OpaqueId" }, "workflow": { "type": "string", "const": "tts" }, "model": { "type": "object", "additionalProperties": false, "required": [ "id", "version" ], "properties": { "id": { "type": "string", "maxLength": 128 }, "version": { "type": "string", "maxLength": 128 } } }, "input": { "type": "object", "description": "A verified text Artifact. Inline text remains unavailable until it is encrypted into a staged Artifact before durable admission.", "additionalProperties": false, "required": [ "text_artifact_id" ], "properties": { "text_artifact_id": { "$ref": "#/components/schemas/OpaqueId" } } }, "configuration": { "type": "object", "additionalProperties": false, "required": [ "voice_id", "output_format" ], "properties": { "voice_id": { "type": "string", "maxLength": 128 }, "voice_reference_id": { "$ref": "#/components/schemas/ResourceId", "description": "Optional tenant-owned saved Voice. The server resolves its defaults and sensitive reference audio; clients never provide a reference URL or object key." }, "catalog_voice_id": { "$ref": "#/components/schemas/ResourceId", "description": "Optional platform catalog presentation voice. It is mutually exclusive with voice_reference_id. The server requires its immutable model/version/base binding to match voice_id, validates language coverage, and snapshots its engine-native defaults before durable admission." }, "language": { "type": "string", "maxLength": 32 }, "output_format": { "type": "string", "enum": [ "wav", "mp3", "flac" ] }, "sample_rate_hz": { "type": "integer", "enum": [ 16000, 22050, 24000, 44100, 48000 ] }, "speed": { "type": "number", "minimum": 0.5, "maximum": 2 }, "model_parameters": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] } } } }, "client_reference": { "type": "string", "maxLength": 128 } } }, "CreateProjectRequest": { "type": "object", "additionalProperties": false, "required": [ "slug", "display_name" ], "properties": { "slug": { "type": "string", "minLength": 2, "maxLength": 63, "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "DownloadAuthorization": { "type": "object", "additionalProperties": false, "required": [ "method", "url", "expires_at" ], "properties": { "method": { "type": "string", "const": "GET" }, "url": { "type": "string", "format": "uri" }, "expires_at": { "$ref": "#/components/schemas/Timestamp" } } }, "DubbingCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "project_id", "source_artifact_id", "target_languages" ], "properties": { "project_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "source_artifact_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "source_language": { "type": "string", "maxLength": 32 }, "target_languages": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "type": "string", "maxLength": 32 } } } }, "DubbingProject": { "type": "object", "additionalProperties": false, "required": [ "id", "project_id", "source_artifact_id", "target_languages", "created_at", "updated_at" ], "description": "tracks is present on single-project reads and on create and stage admission; the listing projection omits it and reports target languages only.", "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "project_id": { "type": "string", "maxLength": 128 }, "source_artifact_id": { "type": "string", "maxLength": 128 }, "source_language": { "type": "string", "maxLength": 32 }, "target_languages": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "tracks": { "type": "array", "items": { "$ref": "#/components/schemas/DubbingTrack" } }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "DubbingProjectList": { "type": "object", "additionalProperties": false, "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DubbingProject" } }, "next_cursor": { "type": "string", "maxLength": 512 } } }, "DubbingSegmentList": { "type": "object", "additionalProperties": false, "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DubbingSegment" } }, "next_cursor": { "type": "string", "maxLength": 512 } } }, "DubbingSegment": { "type": "object", "additionalProperties": false, "required": [ "id", "index", "start_ms", "end_ms", "source_text" ], "description": "translated_text, synthesis_state, and needs_reprocess are present only for a language-filtered listing.", "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "index": { "type": "integer", "minimum": 0 }, "start_ms": { "type": "integer", "minimum": 0 }, "end_ms": { "type": "integer", "minimum": 0 }, "speaker": { "type": "string", "maxLength": 64 }, "source_text": { "type": "string", "maxLength": 5000 }, "translated_text": { "type": "string", "maxLength": 5000 }, "synthesis_state": { "type": "string", "maxLength": 32 }, "needs_reprocess": { "type": "boolean" } } }, "DubbingSegmentsEditRequest": { "type": "object", "additionalProperties": false, "required": [ "segments" ], "properties": { "segments": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/DubbingSegmentEdit" } } } }, "DubbingSegmentEdit": { "type": "object", "additionalProperties": false, "required": [ "id" ], "description": "An omitted field is left unchanged. translations maps a target language onto its replacement text for this segment.", "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "start_ms": { "type": "integer", "minimum": 0 }, "end_ms": { "type": "integer", "minimum": 0 }, "speaker": { "type": "string", "maxLength": 64 }, "source_text": { "type": "string", "maxLength": 5000 }, "translations": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 5000 } } } }, "DubbingSegmentsEditResult": { "type": "object", "additionalProperties": false, "required": [ "edited_segments", "marked_track_segments" ], "description": "Counts only, so the result is safe to keep as audit metadata and as a stored idempotency replay record.", "properties": { "edited_segments": { "type": "integer", "minimum": 0 }, "marked_track_segments": { "type": "integer", "minimum": 0 } } }, "DubbingStageAdmitRequest": { "type": "object", "additionalProperties": false, "description": "An omitted or empty languages list admits the stage on every track of the project. Transcribe requires the list to be omitted or empty, one immutable approved ASR model, and an explicit mode. Translate and synthesize each require exactly one target language and one immutable approved model selection because each protected plan and Job belongs to one track. Translate also requires an explicit quality.", "properties": { "languages": { "type": "array", "maxItems": 24, "items": { "type": "string", "maxLength": 32 } }, "model": { "type": "object", "additionalProperties": false, "description": "Required for transcribe, translate, and synthesize; rejected for mux.", "required": [ "id", "version" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "version": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "quality": { "type": "string", "enum": [ "fast", "cinematic", "autofit" ], "description": "Required only for translate; rejected for other stages." }, "mode": { "type": "string", "enum": [ "fast", "accurate" ], "description": "Required only for transcribe; rejected for other stages." } } }, "DubbingTrack": { "type": "object", "additionalProperties": false, "required": [ "language" ], "properties": { "language": { "type": "string", "maxLength": 32 }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/DubbingStageState" } } } }, "DubbingStageState": { "type": "object", "additionalProperties": false, "required": [ "stage", "status", "updated_at" ], "properties": { "stage": { "$ref": "#/components/schemas/DubbingStage" }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "canceled" ] }, "job_id": { "$ref": "#/components/schemas/OpaqueId" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "DubbingStage": { "type": "string", "enum": [ "transcribe", "translate", "synthesize", "mux" ] }, "ErrorEnvelope": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "request_id", "details" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } }, "Glossary": { "type": "object", "additionalProperties": false, "required": [ "project_id", "terms" ], "properties": { "project_id": { "$ref": "#/components/schemas/OpaqueId" }, "terms": { "type": "array", "maxItems": 256, "items": { "$ref": "#/components/schemas/GlossaryTerm" } } } }, "GlossaryReplaceRequest": { "type": "object", "additionalProperties": false, "required": [ "terms" ], "description": "The complete replacement glossary. Terms are unique on the language and term pair; an empty list clears the glossary.", "properties": { "terms": { "type": "array", "maxItems": 256, "items": { "$ref": "#/components/schemas/GlossaryTerm" } } } }, "GlossaryTerm": { "type": "object", "additionalProperties": false, "required": [ "term", "replacement", "source" ], "properties": { "term": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Must carry no leading or trailing whitespace." }, "replacement": { "type": "string", "minLength": 1, "maxLength": 256 }, "language": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9-]*$" }, "source": { "type": "string", "enum": [ "auto", "manual" ] } } }, "Job": { "type": "object", "additionalProperties": false, "required": [ "id", "project_id", "workflow", "state", "model_id", "model_version", "progress_permille", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueId" }, "project_id": { "$ref": "#/components/schemas/OpaqueId" }, "workflow": { "type": "string", "enum": [ "tts" ] }, "state": { "type": "string", "enum": [ "queued", "running", "canceling", "succeeded", "failed", "canceled" ] }, "model_id": { "type": "string" }, "model_version": { "type": "string" }, "progress_permille": { "type": "integer", "minimum": 0, "maximum": 1000 }, "output_artifact_ids": { "type": "array", "items": { "$ref": "#/components/schemas/OpaqueId" } }, "failure_code": { "type": "string" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "completed_at": { "$ref": "#/components/schemas/Timestamp" } } }, "JobAdmission": { "type": "object", "additionalProperties": false, "description": "The durable result returned by Job admission and cancellation.", "required": [ "job_id", "project_id", "state", "progress_permille", "created_at" ], "properties": { "job_id": { "$ref": "#/components/schemas/OpaqueId" }, "project_id": { "$ref": "#/components/schemas/OpaqueId" }, "state": { "type": "string", "enum": [ "queued", "running", "canceling", "succeeded", "failed", "canceled" ] }, "progress_permille": { "type": "integer", "minimum": 0, "maximum": 1000 }, "created_at": { "$ref": "#/components/schemas/Timestamp" } } }, "JobPage": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/JobListItem" } }, "next_cursor": { "type": "string", "maxLength": 512, "description": "Opaque resume cursor; absent on the last page." } } }, "JobListItem": { "type": "object", "additionalProperties": false, "description": "Customer-safe listing projection. It never carries request snapshots, Artifacts, or compute topology.", "required": [ "id", "project_id", "workflow", "state", "model_id", "model_version", "progress_permille", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueId" }, "project_id": { "$ref": "#/components/schemas/OpaqueId" }, "workflow": { "type": "string", "maxLength": 64 }, "state": { "type": "string", "enum": [ "queued", "running", "canceling", "succeeded", "failed", "canceled" ] }, "model_id": { "type": "string" }, "model_version": { "type": "string" }, "progress_permille": { "type": "integer", "minimum": 0, "maximum": 1000 }, "failure_code": { "type": "string" }, "client_reference": { "type": "string", "maxLength": 128 }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "completed_at": { "$ref": "#/components/schemas/Timestamp" } } }, "OpaqueId": { "type": "string", "description": "Exactly 16 cryptographically random Base62 characters.", "pattern": "^[A-Za-z0-9]{16}$", "minLength": 16, "maxLength": 16 }, "PatchProjectRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "slug": { "type": "string", "minLength": 2, "maxLength": 63, "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "Project": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "display_name", "created_at", "updated_at" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueId" }, "slug": { "type": "string", "minLength": 2, "maxLength": 63, "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 256 }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "ProjectList": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "next_cursor": { "type": "string", "maxLength": 512 } } }, "PronunciationEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "grapheme", "created_at", "updated_at" ], "description": "Exactly one of phoneme or alias is present.", "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "grapheme": { "type": "string", "minLength": 1, "maxLength": 128 }, "phoneme": { "type": "string", "maxLength": 256 }, "alias": { "type": "string", "maxLength": 256 }, "language": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9-]*$" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } } }, "PronunciationEntryList": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PronunciationEntry" } }, "next_cursor": { "type": "string", "maxLength": 512 } } }, "PronunciationEntryRequest": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "grapheme" ], "description": "Exactly one of phoneme or alias must be supplied; supplying both or neither is a 400. organization_id names the tenant whose lexicon is addressed and is Membership-checked, never trusted on its own.", "properties": { "organization_id": { "$ref": "#/components/schemas/OpaqueId" }, "grapheme": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Must carry no leading or trailing whitespace." }, "phoneme": { "type": "string", "maxLength": 256 }, "alias": { "type": "string", "maxLength": 256 }, "language": { "type": "string", "maxLength": 32, "pattern": "^[A-Za-z0-9-]*$" } } }, "PublicTTSModelList": { "type": "object", "additionalProperties": false, "required": [ "workflow", "models" ], "properties": { "workflow": { "type": "string", "const": "tts" }, "models": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/DashboardTTSModelOptions" } } } }, "DashboardTTSModelOptions": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "voices", "languages", "output_formats", "speed" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "version": { "type": "string", "minLength": 1, "maxLength": 128 }, "voices": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/DashboardTTSVoice" } }, "languages": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "output_formats": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "wav", "mp3", "flac" ] } }, "sample_rates_hz": { "type": "array", "items": { "type": "integer", "enum": [ 16000, 22050, 24000, 44100, 48000 ] } }, "speed": { "$ref": "#/components/schemas/DashboardTTSSpeed" }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardTTSParameter" } } } }, "DashboardTTSParameter": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "type" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "type": "string", "enum": [ "integer", "number", "boolean" ] }, "minimum": { "type": "number" }, "maximum": { "type": "number" }, "optional": { "type": "boolean", "description": "When true, omit this control until the user deliberately sets it." }, "default": { "description": "Required unless optional is true.", "oneOf": [ { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] } } }, "DashboardTTSSpeed": { "type": "object", "additionalProperties": false, "required": [ "minimum", "maximum", "default" ], "properties": { "minimum": { "type": "number", "minimum": 0.5, "maximum": 2 }, "maximum": { "type": "number", "minimum": 0.5, "maximum": 2 }, "default": { "type": "number", "minimum": 0.5, "maximum": 2 } } }, "DashboardTTSVoice": { "type": "object", "additionalProperties": false, "required": [ "id", "display_name" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 120 } } }, "PublicTranscriptionModelList": { "type": "object", "additionalProperties": false, "required": [ "workflow", "models" ], "properties": { "workflow": { "type": "string", "const": "transcription" }, "models": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/DashboardTranscriptionModelOptions" } } } }, "DashboardTranscriptionModelOptions": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "mode", "languages", "language_hints", "timestamp_granularities" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "version": { "type": "string", "minLength": 1, "maxLength": 128 }, "mode": { "type": "string", "enum": [ "fast", "accurate" ] }, "languages": { "type": "array", "maxItems": 64, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "language_hints": { "type": "boolean", "description": "False when the runtime supports automatic detection only; languages is then empty." }, "timestamp_granularities": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": [ "segment", "word" ] } } } }, "ResourceId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$" }, "Timestamp": { "type": "string", "format": "date-time" }, "TranscriptDocument": { "type": "object", "additionalProperties": false, "required": [ "schema", "language", "duration_seconds", "segments" ], "properties": { "schema": { "type": "string", "const": "transcript.v2" }, "language": { "type": "string" }, "duration_seconds": { "type": "number", "minimum": 0 }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptDocumentSegment" } } } }, "TranscriptDocumentSegment": { "type": "object", "additionalProperties": false, "required": [ "start_seconds", "end_seconds", "text", "confidence" ], "properties": { "start_seconds": { "type": "number", "minimum": 0 }, "end_seconds": { "type": "number", "minimum": 0 }, "text": { "type": "string" }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Calibrated runtime score, or null when the approved runtime exposes no score." }, "words": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptDocumentWord" } } } }, "TranscriptDocumentWord": { "type": "object", "additionalProperties": false, "required": [ "start_seconds", "end_seconds", "text", "confidence" ], "properties": { "start_seconds": { "type": "number", "minimum": 0 }, "end_seconds": { "type": "number", "minimum": 0 }, "text": { "type": "string" }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Calibrated runtime score, or null when the approved runtime exposes no score." } } }, "Transcription": { "type": "object", "additionalProperties": false, "required": [ "text" ], "description": "The json response_format returns text alone; verbose_json adds task, language, duration, and segments. The text, srt, and vtt formats are returned as plain documents rather than JSON.", "properties": { "text": { "type": "string" }, "task": { "type": "string", "const": "transcribe" }, "language": { "type": "string" }, "duration": { "type": "number" }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptionSegment" } } } }, "TranscriptionRequest": { "type": "object", "additionalProperties": false, "required": [ "file", "model" ], "properties": { "file": { "type": "string", "format": "binary", "description": "audio/wav, audio/mpeg, audio/flac, or audio/ogg, at most 25 MiB." }, "model": { "type": "string", "minLength": 1, "maxLength": 128 }, "model_version": { "type": "string", "maxLength": 128 }, "language": { "type": "string", "maxLength": 32 }, "response_format": { "type": "string", "enum": [ "json", "text", "verbose_json", "srt", "vtt" ], "default": "json" }, "mode": { "type": "string", "enum": [ "fast", "accurate" ], "default": "accurate", "description": "Selects the billing class the resolved model must match. A mismatch answers 404 model_not_found." }, "timestamp_granularity": { "type": "string", "enum": [ "segment", "word" ], "default": "segment" }, "project_id": { "type": "string", "maxLength": 128, "description": "Extension field. Omitted, the façade resolves the principal's default Project where that is unambiguous." }, "duration_seconds": { "type": "integer", "minimum": 1, "maximum": 14400, "description": "Optional extension. The server measures the media itself when omitted, and verifies any supplied value against the received bytes so a client cannot understate audio-seconds." }, "prompt": { "type": "string", "description": "Accepted, bounded, and ignored. Excluded from the idempotency digest." }, "temperature": { "type": "number", "minimum": 0, "maximum": 1, "description": "Accepted, bounded, and ignored. Excluded from the idempotency digest." }, "stream": { "type": "string", "enum": [ "false" ], "description": "Streaming is not supported here; any other value answers 400 unsupported_parameter. Poll the returned job instead." } } }, "TranscriptionSegment": { "type": "object", "additionalProperties": false, "required": [ "id", "start", "end", "text" ], "properties": { "id": { "type": "integer", "minimum": 0 }, "start": { "type": "number" }, "end": { "type": "number" }, "text": { "type": "string" } } }, "UploadAuthorization": { "type": "object", "additionalProperties": false, "required": [ "artifact_id", "method", "url", "required_headers", "expires_at" ], "properties": { "artifact_id": { "$ref": "#/components/schemas/OpaqueId" }, "method": { "type": "string", "const": "PUT" }, "url": { "type": "string", "format": "uri" }, "required_headers": { "type": "object", "additionalProperties": { "type": "string" } }, "expires_at": { "$ref": "#/components/schemas/Timestamp" } } }, "UploadAuthorizationRequest": { "type": "object", "additionalProperties": false, "required": [ "project_id", "purpose", "media_type", "size_bytes", "sha256" ], "properties": { "project_id": { "$ref": "#/components/schemas/OpaqueId" }, "purpose": { "type": "string", "enum": [ "tts_text", "job_input", "reference_audio", "source_media", "subtitle", "cover_image", "document_import" ] }, "media_type": { "type": "string", "maxLength": 128 }, "size_bytes": { "type": "integer", "minimum": 1 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "declared_duration_seconds": { "type": "integer", "minimum": 1, "maximum": 14400, "description": "Required for audio when the server cannot measure a trustworthy container duration, and for Dubbing source_media video so audio-second work can reserve against its bounded timeline." }, "retention_policy": { "type": "string", "maxLength": 64 } } }, "UsageBreakdown": { "type": "object", "additionalProperties": false, "required": [ "dimension", "from", "to", "groups" ], "properties": { "dimension": { "type": "string", "enum": [ "day", "project", "workflow" ] }, "from": { "$ref": "#/components/schemas/Timestamp" }, "to": { "$ref": "#/components/schemas/Timestamp" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBreakdownGroup" } }, "truncated": { "type": "boolean" } } }, "UsageBreakdownGroup": { "type": "object", "additionalProperties": false, "required": [ "key", "settled_events", "charged_credit_units", "released_credit_units" ], "properties": { "key": { "type": "string" }, "settled_events": { "type": "integer", "minimum": 0 }, "charged_credit_units": { "type": "integer", "minimum": 0 }, "released_credit_units": { "type": "integer", "minimum": 0 } } }, "UsageEventList": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UsageEvent" } }, "next_cursor": { "type": "string", "maxLength": 512 } } }, "UsageEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "credit_units", "settled_at" ], "properties": { "id": { "$ref": "#/components/schemas/OpaqueId" }, "type": { "type": "string", "enum": [ "settlement", "compensation" ] }, "job_id": { "$ref": "#/components/schemas/OpaqueId" }, "workflow": { "type": "string" }, "rating_policy_version": { "type": "string" }, "rated_quantity": { "type": "integer", "minimum": 0 }, "rated_unit": { "type": "string" }, "credit_units": { "type": "integer" }, "settled_at": { "$ref": "#/components/schemas/Timestamp" } } }, "UsageSummary": { "type": "object", "additionalProperties": false, "required": [ "organization_id", "available_credit_units", "active_reservations", "reserved_credit_units", "settled_credit_units", "current_cycle" ], "properties": { "organization_id": { "$ref": "#/components/schemas/OpaqueId" }, "available_credit_units": { "type": "integer", "minimum": 0 }, "allowance_ends_at": { "$ref": "#/components/schemas/Timestamp" }, "allowance": { "type": "object", "additionalProperties": false, "required": [ "starts_at", "ends_at" ], "properties": { "starts_at": { "$ref": "#/components/schemas/Timestamp" }, "ends_at": { "$ref": "#/components/schemas/Timestamp" } } }, "active_reservations": { "type": "integer", "minimum": 0 }, "reserved_credit_units": { "type": "integer", "minimum": 0 }, "settled_credit_units": { "type": "integer", "minimum": 0 }, "current_cycle": { "$ref": "#/components/schemas/UsageCycle" }, "previous_cycle": { "$ref": "#/components/schemas/UsageCycle" } } }, "UsageCycle": { "type": "object", "additionalProperties": false, "required": [ "starts_at", "ends_at", "settled_events", "settled_credit_units", "reserved_credit_units" ], "properties": { "starts_at": { "$ref": "#/components/schemas/Timestamp" }, "ends_at": { "$ref": "#/components/schemas/Timestamp" }, "settled_events": { "type": "integer", "minimum": 0 }, "settled_credit_units": { "type": "integer", "minimum": 0 }, "reserved_credit_units": { "type": "integer", "minimum": 0 } } }, "Voice": { "type": "object", "additionalProperties": false, "required": [ "id", "source", "display_name", "state", "created_at", "updated_at" ], "description": "The customer Voice projection. The owning Organization is deliberately not serialized: a caller already acts inside an authorized Organization.", "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "project_id": { "type": "string", "maxLength": 128 }, "source": { "type": "string", "enum": [ "customer", "catalog" ] }, "display_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 1024 }, "languages": { "type": "array", "items": { "type": "string" } }, "preview_media_type": { "type": "string" }, "default_parameters": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] } }, "facets": { "type": "object", "additionalProperties": { "type": "string" } }, "state": { "type": "string", "enum": [ "draft", "ready", "locked", "deleting", "deleted" ] }, "consent": { "$ref": "#/components/schemas/VoiceConsent" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "locked_at": { "$ref": "#/components/schemas/Timestamp" }, "deleted_at": { "$ref": "#/components/schemas/Timestamp" } } }, "VoiceCloneRequest": { "type": "object", "additionalProperties": false, "required": [ "project_id", "model" ], "properties": { "project_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "model": { "type": "object", "additionalProperties": false, "required": [ "id", "version" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "version": { "type": "string", "minLength": 1, "maxLength": 128 } } } } }, "VoiceConsent": { "type": "object", "additionalProperties": false, "required": [ "principal_id", "attestation_text_version", "reference_artifact_id", "attested_at" ], "properties": { "principal_id": { "type": "string" }, "attestation_text_version": { "type": "string", "maxLength": 64 }, "reference_artifact_id": { "type": "string", "maxLength": 128 }, "attested_at": { "$ref": "#/components/schemas/Timestamp" } } }, "VoiceCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "display_name" ], "description": "Exactly one creation path is required: a reference-audio Artifact with consent, an active catalog_voice_id with project_id, or a succeeded design_preview_job_id with project_id.", "oneOf": [ { "required": [ "display_name", "reference_audio_artifact_id", "consent" ] }, { "required": [ "display_name", "project_id", "catalog_voice_id" ] }, { "required": [ "display_name", "project_id", "design_preview_job_id" ] } ], "properties": { "project_id": { "type": "string", "maxLength": 128 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 1024 }, "reference_audio_artifact_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "catalog_voice_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$" }, "design_preview_job_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$", "description": "Public identifier of a succeeded tenant-owned voice_design_preview Job. The server persists its internal Job ID as immutable Voice provenance." }, "consent": { "type": "object", "additionalProperties": false, "required": [ "attestation_text_version" ], "properties": { "attestation_text_version": { "type": "string", "minLength": 1, "maxLength": 64 } } } } }, "VoiceDesignPreviewRequest": { "type": "object", "additionalProperties": false, "required": [ "project_id", "description", "voice_id", "language", "model" ], "properties": { "project_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Comma-separated reviewed OmniVoice attributes, with at most one value from each category. Examples include female, young adult, moderate pitch, whisper, british accent, and 四川话. Free-form prose and an English accent combined with a Chinese dialect are rejected." }, "voice_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "language": { "type": "string", "minLength": 1, "maxLength": 32 }, "model": { "type": "object", "additionalProperties": false, "required": [ "id", "version" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "version": { "type": "string", "minLength": 1, "maxLength": 128 } } } } }, "VoiceList": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Voice" } }, "next_cursor": { "type": "string", "maxLength": 512 } } }, "VoiceLockRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 512 } } }, "VoiceUpdateRequest": { "type": "object", "additionalProperties": false, "description": "An omitted field is left unchanged.", "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 1024 } } }, "VoiceUsage": { "type": "object", "additionalProperties": false, "required": [ "voice_id", "job_count", "job_count_truncated" ], "description": "job_count stops at a server bound; job_count_truncated reports that the bound was reached rather than scanning the full Job history.", "properties": { "voice_id": { "$ref": "#/components/schemas/ResourceId" }, "job_count": { "type": "integer", "minimum": 0 }, "job_count_truncated": { "type": "boolean" } } } }, "securitySchemes": { "DeveloperCredential": { "type": "http", "scheme": "bearer", "bearerFormat": "VoiceStudio API credential" } } }, "x-voicestudio-contract": { "product": "cloud", "audience": "public-developer", "availability": "unavailable", "source_repository": "debpalash/vssaas", "source_commit": "a5423918e61e9be863f24e275cdeb31a623c8435", "source_sha256": "dd7598073b6fb4c27dcd22113fc445ee921fe4c7dc3204835a9e6530b8345ec3", "generated_contract_version": "1.0.0", "excluded_audiences": [ "website-edge", "desktop-client", "dashboard-bff", "operator", "internal-service" ] } }