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

VoiceService

Localize a voice

Generate localized prompt candidates that make an existing voice speak a target language while keeping the same speaker identity. Returns multiple candidates on a draft; listen to them and confirm your pick with Approve a localization. Unapproved drafts expire after 3 days.

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

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}:localize is still supported.

Localization is a two-call flow with a human in the middle:

  1. Localize (this endpoint) — generates localized prompt candidates and saves them on a hidden draft.
  2. Approve — you listen to the candidates, pick one, and it becomes the voice's prompt for that language.

Candidates are not automatically scored — a person is expected to listen to each previewAudio and choose by ear.

Use candidateCount to keep the response small when you don't need every option. Candidates are ordered by historical approval rates measured across all languages, so asking for fewer gives you the engine that performs best on average — not necessarily the best one for your target language. When quality in a specific language matters, request more candidates and compare.

Behavior worth knowing:

  • Drafts expire. An unapproved draft is cleaned up after 3 days. Drafts don't appear in your voice listings.
  • Re-localizing the same voice and language replaces the draft's candidates — candidate IDs from an earlier response stop resolving. Always approve from the most recent localize response.
  • Language limit. A voice can hold at most 20 languages (as reported by promptLanguages). Localizing a voice at the cap is rejected with 400 INVALID_ARGUMENT before any synthesis runs.
  • Region required. de is rejected where de-DE is accepted. See Languages for the supported catalog.

Localization calls consume credits and are rate limited separately from speech synthesis. A 429 means the per-tier rate limit was exceeded — safe to retry after backing off.

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 to localize. Expected format: {workspace}__{voice}.

Body

application/json

targetLanguagestringrequired

The language to localize the voice into, as a BCP-47 code with a region — e.g. de-DE, es-MX, pt-BR. Matching is case- and separator-insensitive (es_MX and ES-mx are accepted). A bare language code with no region (de) is rejected, and auto is not supported. See Languages for the supported catalog.

targetTranscriptionstring

Optional pre-translated text in the target language, up to 200 characters. When supplied, the automatic translation step is skipped and the candidates speak this text instead.

candidateCountinteger

Optional. Caps how many candidates are returned, from 1 to 3. Omit (or send 0) to get one candidate per available synthesis engine, which is the default.

Fewer candidates may come back than you ask for: the number of available engines sets the ceiling, and candidateCount can only lower it, never raise it.

Candidates are kept in a fixed order derived from historical approval rates across all languages. That ranking is global. The strongest engine for any one language can differ from it. A low candidateCount gives you the historically best-performing engine, which may not produce the best candidate for your target language. Request more candidates when localization quality for a specific language matters.

Response

200 - application/json

draftVoiceIdstring

Identifier of the draft holding the candidates. Pass it to Approve a localization. Drafts are not listed among your voices and expire after 3 days if never approved.

candidatesobject[]

Localized prompt candidates, one per synthesis engine. Listen to each preview and pick the one that sounds most natural and native.

Show child attributes

candidateIdstring

Identifier for this candidate. Pass it to Approve a localization together with the draftVoiceId. Candidate IDs are replaced if you localize the same voice and language again — always approve from the most recent localize response.

enginestring

Opaque label identifying which synthesis engine produced this candidate (e.g. engine_a). Labels are stable across responses; candidates from different engines have different strengths, so listen to each.

previewAudiostring

Base64-encoded WAV preview of the candidate speaking the target-language text, typically 9-15 seconds.

transcriptionstring

The target-language text this candidate speaks — the automatic translation of the voice's source text, or your targetTranscription verbatim when it was supplied.

qualityScorenumber

Deprecated. Always 0.0 and scheduled for removal — candidates are not automatically scored. Listen to each candidate's previewAudio and choose by ear.