VoiceStudioDocs
Cloud reference

Voices

List Voices

GET
/v1/voices

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.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Query Parameters

project_id?string

Required unless source=catalog. The Project whose Organization's customer Voices are listed.

Length1 <= length <= 128
source?string

Defaults to customer.

Default"customer"

Value in

  • "customer"
  • "catalog"
cursor?string
Lengthlength <= 512
limit?integer
Range1 <= value <= 100
Default25

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X GET "https://example.com/v1/voices"
json
{
  "items": [
    {
      "id": "string",
      "project_id": "string",
      "source": "customer",
      "display_name": "string",
      "description": "string",
      "languages": [
        "string"
      ],
      "preview_media_type": "string",
      "default_parameters": {
        "property1": "string",
        "property2": "string"
      },
      "facets": {
        "property1": "string",
        "property2": "string"
      },
      "state": "draft",
      "consent": {
        "principal_id": "string",
        "attestation_text_version": "string",
        "reference_artifact_id": "string",
        "attested_at": "2019-08-24T14:15:22Z"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "locked_at": "2019-08-24T14:15:22Z",
      "deleted_at": "2019-08-24T14:15:22Z"
    }
  ],
  "next_cursor": "string"
}

Create Voice

POST
/v1/voices

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.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key*string

Replay key for the Voice surface, which bounds keys at 512 characters rather than the 128 used elsewhere.

Length1 <= length <= 512

Request Body

application/json

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.

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.

project_id?string
Lengthlength <= 128
display_name*string
Length1 <= length <= 120
description?string
Lengthlength <= 1024
reference_audio_artifact_id*string
Length1 <= length <= 128
catalog_voice_id?string
Match^[A-Za-z0-9_-]{16}$
design_preview_job_id?string

Public identifier of a succeeded tenant-owned voice_design_preview Job. The server persists its internal Job ID as immutable Voice provenance.

Match^[A-Za-z0-9_-]{16}$
consent*

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X POST "https://example.com/v1/voices" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "string"
  }'
json
{
  "id": "string",
  "project_id": "string",
  "source": "customer",
  "display_name": "string",
  "description": "string",
  "languages": [
    "string"
  ],
  "preview_media_type": "string",
  "default_parameters": {
    "property1": "string",
    "property2": "string"
  },
  "facets": {
    "property1": "string",
    "property2": "string"
  },
  "state": "draft",
  "consent": {
    "principal_id": "string",
    "attestation_text_version": "string",
    "reference_artifact_id": "string",
    "attested_at": "2019-08-24T14:15:22Z"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "locked_at": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z"
}

Create Voice Design Preview

POST
/v1/voices/design-previews

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.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key*string

Replay key for the Voice surface, which bounds keys at 512 characters rather than the 128 used elsewhere.

Length1 <= length <= 512

Request Body

application/json

project_id*string
Length1 <= length <= 128
description*string

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.

Length1 <= length <= 512
voice_id*string
Length1 <= length <= 128
language*string
Length1 <= length <= 32
model*

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X POST "https://example.com/v1/voices/design-previews" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "string",
    "description": "string",
    "voice_id": "string",
    "language": "string",
    "model": {
      "id": "string",
      "version": "string"
    }
  }'
json
{
  "id": "stringstringstri",
  "project_id": "stringstringstri",
  "workflow": "tts",
  "state": "queued",
  "model_id": "string",
  "model_version": "string",
  "progress_permille": 0,
  "output_artifact_ids": [
    "stringstringstri"
  ],
  "failure_code": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}

Get Voice

GET
/v1/voices/{voice_id}

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

voice_id*string
Match^[A-Za-z0-9_-]{16}$

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X GET "https://example.com/v1/voices/string"
json
{
  "id": "string",
  "project_id": "string",
  "source": "customer",
  "display_name": "string",
  "description": "string",
  "languages": [
    "string"
  ],
  "preview_media_type": "string",
  "default_parameters": {
    "property1": "string",
    "property2": "string"
  },
  "facets": {
    "property1": "string",
    "property2": "string"
  },
  "state": "draft",
  "consent": {
    "principal_id": "string",
    "attestation_text_version": "string",
    "reference_artifact_id": "string",
    "attested_at": "2019-08-24T14:15:22Z"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "locked_at": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z"
}

Update Voice

PATCH
/v1/voices/{voice_id}

Updates the mutable presentation fields. An omitted field is left unchanged; consent and the reference Artifact are immutable.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

voice_id*string
Match^[A-Za-z0-9_-]{16}$

Header Parameters

Idempotency-Key*string

Replay key for the Voice surface, which bounds keys at 512 characters rather than the 128 used elsewhere.

Length1 <= length <= 512

Request Body

application/json

An omitted field is left unchanged.

display_name?string
Length1 <= length <= 120
description?string
Lengthlength <= 1024

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X PATCH "https://example.com/v1/voices/string" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{}'
json
{
  "id": "string",
  "project_id": "string",
  "source": "customer",
  "display_name": "string",
  "description": "string",
  "languages": [
    "string"
  ],
  "preview_media_type": "string",
  "default_parameters": {
    "property1": "string",
    "property2": "string"
  },
  "facets": {
    "property1": "string",
    "property2": "string"
  },
  "state": "draft",
  "consent": {
    "principal_id": "string",
    "attestation_text_version": "string",
    "reference_artifact_id": "string",
    "attested_at": "2019-08-24T14:15:22Z"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "locked_at": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z"
}

Delete Voice

DELETE
/v1/voices/{voice_id}

Begins Voice deletion. The idempotency digest is target-bound, so the same key cannot be replayed against a different Voice.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

voice_id*string
Match^[A-Za-z0-9_-]{16}$

Header Parameters

Idempotency-Key*string

Replay key for the Voice surface, which bounds keys at 512 characters rather than the 128 used elsewhere.

Length1 <= length <= 512

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X DELETE "https://example.com/v1/voices/string" \
  -H "Idempotency-Key: string"
Empty

Lock Voice

POST
/v1/voices/{voice_id}/lock

Locks a ready Voice against further mutation. A Voice whose state does not allow the transition answers 409 conflict.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

voice_id*string
Match^[A-Za-z0-9_-]{16}$

Header Parameters

Idempotency-Key*string

Replay key for the Voice surface, which bounds keys at 512 characters rather than the 128 used elsewhere.

Length1 <= length <= 512

Request Body

application/json

reason?string
Lengthlength <= 512

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X POST "https://example.com/v1/voices/string/lock" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{}'
json
{
  "id": "string",
  "project_id": "string",
  "source": "customer",
  "display_name": "string",
  "description": "string",
  "languages": [
    "string"
  ],
  "preview_media_type": "string",
  "default_parameters": {
    "property1": "string",
    "property2": "string"
  },
  "facets": {
    "property1": "string",
    "property2": "string"
  },
  "state": "draft",
  "consent": {
    "principal_id": "string",
    "attestation_text_version": "string",
    "reference_artifact_id": "string",
    "attested_at": "2019-08-24T14:15:22Z"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "locked_at": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z"
}

Clone Voice

POST
/v1/voices/{voice_id}/clone

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.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

voice_id*string
Match^[A-Za-z0-9_-]{16}$

Header Parameters

Idempotency-Key*string

Replay key for the Voice surface, which bounds keys at 512 characters rather than the 128 used elsewhere.

Length1 <= length <= 512

Request Body

application/json

project_id*string
Length1 <= length <= 128
model*

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X POST "https://example.com/v1/voices/string/clone" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "string",
    "model": {
      "id": "string",
      "version": "string"
    }
  }'
json
{
  "job_id": "stringstringstri",
  "project_id": "stringstringstri",
  "state": "queued",
  "progress_permille": 0,
  "created_at": "2019-08-24T14:15:22Z"
}

Unlock Voice

POST
/v1/voices/{voice_id}/unlock

Returns a locked Voice to the ready state.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

voice_id*string
Match^[A-Za-z0-9_-]{16}$

Header Parameters

Idempotency-Key*string

Replay key for the Voice surface, which bounds keys at 512 characters rather than the 128 used elsewhere.

Length1 <= length <= 512

Request Body

application/json

reason?string
Lengthlength <= 512

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X POST "https://example.com/v1/voices/string/unlock" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{}'
json
{
  "id": "string",
  "project_id": "string",
  "source": "customer",
  "display_name": "string",
  "description": "string",
  "languages": [
    "string"
  ],
  "preview_media_type": "string",
  "default_parameters": {
    "property1": "string",
    "property2": "string"
  },
  "facets": {
    "property1": "string",
    "property2": "string"
  },
  "state": "draft",
  "consent": {
    "principal_id": "string",
    "attestation_text_version": "string",
    "reference_artifact_id": "string",
    "attested_at": "2019-08-24T14:15:22Z"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "locked_at": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z"
}

Get Voice Usage

GET
/v1/voices/{voice_id}/usage

Bounded Voice usage projection. The Job count stops at a server bound and reports truncation rather than scanning the full Job history.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

voice_id*string
Match^[A-Za-z0-9_-]{16}$

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X GET "https://example.com/v1/voices/string/usage"
json
{
  "voice_id": "string",
  "job_count": 0,
  "job_count_truncated": true
}

Get Voice Preview

GET
/v1/voices/{voice_id}/preview

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.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

voice_id*string
Match^[A-Za-z0-9_-]{16}$

Response Body

application/json

application/json

application/json

application/json

bash
curl -X GET "https://example.com/v1/voices/string/preview"
Empty

Usage

Previous Page

Dubbing

Next Page