Realtime TTS-2 is live. Built for realtime conversation that feels human. Read the Realtime TTS-2 announcement

VoiceService

Update a voice

Inworld Voice API reference: update a custom voice's name, description, tags, and other settings.

PATCH/voices/v1/voices/{voiceId}

Short URL path: You can omit /workspaces/{workspace} from the path. When omitted, the workspace comes from your API key. The previous full URL /voices/v1/workspaces/{workspace}/voices/{voice} continues to be supported.

Setting gender, age group, and categories on a cloned voice

You cannot set these fields when cloning. The CloneVoice request carries only displayName, languageCode (or the legacy langCode), voiceSamples, description, tags, and audioProcessingConfig. Anything else in the body, including gender, ageGroup, and categories, is silently ignored. To set them, PATCH the voice after cloning.

The voice's language cannot change after creation. UpdateVoice cannot change languageCode/langCode.

The updateMask query parameter controls which fields are applied. Any field in the body but missing from the mask is silently ignored. Mask paths use snake_case field names (e.g. age_group), even though the request body uses camelCase (ageGroup). Passing the camelCase form (?updateMask=gender,ageGroup) silently fails for multi-word fields.

bash
curl -X PATCH \
  "https://api.inworld.ai/voices/v1/voices/<voice-id>?updateMask=gender,age_group,categories" \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gender": "female",
    "ageGroup": "young",
    "categories": ["companions"]
  }'

<voice-id> is the voiceId returned by CloneVoice, in the format {workspace}__{voice}.

Response (200):

json
{
  "name": "workspaces/{workspace}/voices/{voice}",
  "voiceId": "{workspace}__{voice}",
  "langCode": "EN_US",
  "languageCode": "en-US",
  "displayName": "John",
  "description": "Cloned voice for narrations.",
  "tags": ["demo", "clone"],
  "source": "IVC",
  "gender": "female",
  "ageGroup": "young",
  "categories": ["companions"],
  "promptLanguages": ["en-US"]
}

Accepted values:

  • gender: "male", "female", "neutral"
  • ageGroup: "young", "middle_aged", "elderly"
  • categories: "companions", "developer_assistants", "education_training", "enterprise", "healthcare", "interactive_media"

An invalid categories value returns HTTP 400 and rejects the entire request, including valid categories in the same list. In contrast, gender and ageGroup are silently dropped if you misuse the mask.

Authorizations

Authorizationstringrequired

Your API key. Read permissions are required for GET endpoints. Write permissions are required for POST, PATCH, and DELETE endpoints.

For Basic authentication, please populate Basic $INWORLD_API_KEY. You can create a key in one command with the Inworld CLI: inworld workspace add-key.

Path Parameters

voiceIdstringrequired

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

Query Parameters

updateMaskstring

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.

Body

application/json

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.

genderenum<string>

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

Available options:malefemaleneutral

ageGroupenum<string>

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

Available options:youngmiddle_agedelderly

categoriesenum<string>[]

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

200 - application/json

voiceIdstring

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

langCodeenum<string>

Primary language of the voice in upper-snake format (e.g. EN_US). Note that when filtering via lang_code, you can pass BCP-47 (en-US), underscore form (en_US), or a language prefix (en) — but the response always returns upper-snake.

Available options:EN_USZH_CNKO_KRJA_JPRU_RUAUTOIT_ITES_ESPT_BRDE_DEFR_FRAR_SAPL_PLNL_NLHI_INHE_IL

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 identifier. Workspace voices use workspaces/{workspace}/voices/{voice}; system and shared voices may use a bare identifier. For synthesis and audio previews, use voiceId unchanged instead of constructing a resource path.

sourceenum<string>

Voice provenance: SYSTEM (Inworld system voice), IVC (instant voice clone), TVD (voice design), PVC (professional or supplied custom voice), or OTHER. Treat provenance separately from community-sharing and ownership metadata.

Available options:SYSTEMIVCTVDPVCOTHER

genderenum<string>

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

Available options:malefemaleneutral

ageGroupenum<string>

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

Available options:youngmiddle_agedelderly

categoriesenum<string>[]

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

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

promptLanguagesstring[]

Every language the voice can speak, in BCP-47 format (e.g. en-US): its source language first, then each language it has been localized to. A voice without localizations has one entry; a voice whose language is detected automatically has none. Returned by both listing and getting a voice.

ownedboolean

For a community voice result, whether the calling workspace owns the voice. Interpret alongside community-sharing metadata; this field is not a general test for whether synthesis is permitted.