v1

latestOpenAPI 3.0.02026-07-262088144.5 KB

VoiceService

Updates an existing voice

patch/voices/v1/voices/{voiceId}

Path parameters

voiceIdstring required

Voice ID containing the voice to update. Expected format: {workspace}__{voice}.

Query parameters

updateMaskstring

Example:gender,age_group

Comma-separated list of fields to update. Paths use snake_case field names, even though the request body uses camelCase. Supported paths: display_name, description, tags, gender, age_group, categories. Fields present in the body but omitted from updateMask are ignored.

Request body

displayNamestring

The human-readable name shown anywhere the voice is listed or selected. Keep it short and distinctive so users can find it easily.

descriptionstring

Description of the voice, such as the voice's tone, accent, use cases, or other relevant attributes. Helpful for search and selection.

tagsstring[]

Free-form labels for filtering, grouping, and discovery (e.g. ["british", "calm"]). Structured metadata like gender and age has dedicated fields — see gender, ageGroup, and categories below.

gender'male' | 'female' | 'neutral'

Voice gender. Include gender in updateMask to apply this field.

ageGroup'young' | 'middle_aged' | 'elderly'

Age group of the voice. Include age_group (snake_case) in updateMask to apply this field.

categoriesstring[]

Use-case categories the voice belongs to. Include categories in updateMask to apply this field. An invalid value returns HTTP 400 and rejects the whole request (all-or-nothing), unlike gender/ageGroup which are silently dropped when the mask is wrong.

Response

A successful response.

voiceIdstring

Voice ID. SYSTEM voices use a simple name (e.g. Alex); IVC voices are workspace-prefixed ({workspace}__{voice}).

Legacy enum encoding of the voice's language. The full accepted set is much larger than the values listed here: every supported locale has an enum name (the locale with - replaced by _, uppercased — en-GB becomes EN_GB). Prefer the languageCode string field on new integrations. AUTO (or omitting the language entirely) auto-detects the language.

languageCodestring

Canonical wire form of the voice's primary language as a single string (e.g. en-US, es-MX, vi). Populated on every read alongside the legacy langCode enum. Immutable after creation.

displayNamestring

The human-readable name shown anywhere the voice is listed or selected.

descriptionstring

Longer blurb that explains the voice's tone, accent, use cases, or other relevant attributes.

tagsstring[]

Free-form labels for filtering, grouping, and discovery (e.g. british, calm).

namestring

Resource name. Format: workspaces/{workspace}/voices/{voice}.

source'SYSTEM' | 'IVC' | 'PVC'

Origin of the voice:

SYSTEM: Built-in voice provided by Inworld, visible to all workspaces.
IVC: Voice cloned from audio or created via Voice Design — owned by your workspace only.
PVC: Professional Voice Clone.

gender'male' | 'female' | 'neutral' | ''

Voice gender (male, female, neutral). Empty string if unspecified. Voices with no gender are excluded when filtering with an explicit gender = predicate.

ageGroup'young' | 'middle_aged' | 'elderly' | ''

Age group of the voice (young, middle_aged, elderly). Empty string if unspecified.

categoriesstring[]

Use-case categories the voice belongs to. Filterable with the : (has) operator.

Supported values: companions, enterprise, education_training, developer_assistants, healthcare, interactive_media.

promptLanguagesstring[]

Languages the voice can handle, in BCP-47 format (e.g. en-US). May differ from langCode for multilingual voices.

Example response

{
  "name": "workspaces/your_workspace_id/voices/my_voice_clone_demo_20260218_223134z",
  "voiceId": "your_workspace_id__my_voice_clone_demo_20260218_223134z",
  "langCode": "EN_US",
  "displayName": "John",
  "description": "Cloned voice for narrations.",
  "tags": [
    "demo",
    "clone"
  ],
  "categories": [],
  "source": "IVC",
  "gender": "",
  "ageGroup": "",
  "promptLanguages": [
    "en-US"
  ]
}