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

VoiceService

Approve a localization

Confirm one candidate from a Localize a voice response. The chosen candidate becomes the voice's prompt for the target language, and the draft is deleted. Approving replaces any existing prompt the voice had for that language.

POST/voices/v1/voices/{voiceId}:approveLocalization

Short URL Path: You can omit /workspaces/{workspace} from the path. The service then derives the workspace from your API key. The full path /voices/v1/workspaces/{workspace}/voices/{voice}:approveLocalization is still supported.

This is the second call in the localization flow. Start with Localize a voice. The {voiceId} in the URL must identify the voice the draft was created from. The service reads the target language from the draft; you do not pass it in this call.

Approve is one-shot. It sets the chosen candidate as the voice's prompt for that language, replaces any prompt the voice already had for that language, and deletes the draft. Changing your mind afterward means running localize again. There is no way to remove a single language from a voice — re-approving a language replaces its prompt, and only deleting the voice removes everything.

A 404 NOT_FOUND on this call usually means the candidate was superseded — localizing the same voice and language again replaces the draft's candidates. Re-run localize and approve from the newest response. A 429 (rate limit) is harmless here: the draft still exists, so the call can simply be retried.

After approval, generate speech in the new language by passing the same voiceId with the target language — the voice now uses its localized prompt for that language. See Languages.

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 of the voice the draft was created from. Must match the voice used in the localize call.

Body

application/json

draftVoiceIdstringrequired

The draftVoiceId returned by the localize call.

candidateIdstringrequired

The chosen candidate's candidateId from the same localize response.

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.