Skip to main content
POST
cURL
Short URL Path: /workspaces/{workspace} is no longer required in the path for simplicity and clarity. When omitted, the workspace is derived from your API key. The previous URL with the full path /voices/v1/workspaces/{workspace}/voices/{voice}:approveLocalization would continue to be supported.
The second half of the two-call localization flow — see Localize a voice for the first half. The {voiceId} in the URL must be the voice the draft was created from; the target language is not passed, it is read from the draft.
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

Authorization
string
header
required

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

voiceId
string
required

Voice ID of the voice the draft was created from. Must match the voice used in the localize call.

Pattern: [^/]+

Body

application/json

Request message for ApproveLocalizedPrompt custom method. The target language is not passed — it is read from the draft.

draftVoiceId
string
required

The draftVoiceId returned by the localize call.

candidateId
string
required

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

Response

A successful response. Returns the updated voice; promptLanguages now includes the new language.

Voice resource representing a voice configuration.

voiceId
string
read-only

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

langCode
enum<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_US,
ZH_CN,
KO_KR,
JA_JP,
RU_RU,
AUTO,
IT_IT,
ES_ES,
PT_BR,
DE_DE,
FR_FR,
AR_SA,
PL_PL,
NL_NL,
HI_IN,
HE_IL
languageCode
string

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.

displayName
string

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

description
string

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

tags
string[]

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

name
string

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

source
enum<string>

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.
Available options:
SYSTEM,
IVC,
PVC
gender
enum<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:
male,
female,
neutral,
ageGroup
enum<string>

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

Available options:
young,
middle_aged,
elderly,
categories
enum<string>[]

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

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

Available options:
companions,
enterprise,
education_training,
developer_assistants,
healthcare,
interactive_media
promptLanguages
string[]

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