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

VoiceService

Design a voice

Inworld Voice API reference: design a voice from a text description and get up to three preview voices to choose from.

POST/voices/v1/voices:design

Design a voice from a text description. This endpoint generates up to three preview voices. Choose a preview and add it to your voice library with Publish Voice.

For a guided workflow, see Voice Design.

Preview text length: The previewText must result in generated audio that is 1-30 seconds long (~50-400 characters in English).

Design mode: By default, AI turns your free-text designPrompt into a structured voice profile. To provide the profile yourself and use it directly, send designPromptMode: DESIGN_PROMPT_MODE_VERBATIM. See Voice Design best practices.

Choosing the voice's language

Set the language with languageCode — the canonical locale string, e.g. "en-US", "en-GB", "vi":

  • Matching is forgiving — case- and separator-insensitive (en-gb, EN_GB, and en-GB are equivalent). A bare language code with no region ("en", "pt") selects the language's default accent.
  • Accent is part of the locale — there is no separate accent field. To design a British-accented voice, send "en-GB"; for Australian, "en-AU".
  • Auto-detect — omit the field (or send "auto") to auto-detect the language.
  • Validation — values outside the supported catalog are rejected with INVALID_ARGUMENT; nothing is silently coerced.

See Languages for the supported languages.

Legacy langCode. Older integrations set the language via the langCode enum (the locale with - replaced by _, uppercased — en-GB → EN_GB; AUTO = auto-detect). It remains accepted, and responses populate it alongside languageCode. Set at most one of the two on a request; use languageCode in new code.

<RequestField body="languageCode" type="string"> Canonical locale string, e.g. en-US, en-GB, vi. See Choosing the voice's language above. </RequestField>

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.

Body

application/json

voiceDesignConfigobject

Voice design configuration for generating the preview. If not provided, defaults to generating 1 sample.

Show child attributes

numberOfSamplesinteger

Number of voice samples to generate. Must be between 1 and 3. Default is 1 if not provided.

designPromptstringrequired

Text description of the desired voice. Must be in English and up to 1000 characters; descriptions under 30 rarely produce a useful voice. For best results, include age, gender, accent, pitch, pace, and tone. See Voice Design Best Practices for more details.

Example: "A middle-aged male voice with a clear British accent speaking at a steady pace and with a neutral tone."

designPromptModeenum<string>default: "DESIGN_PROMPT_MODE_ASSISTED"

How designPrompt is interpreted. By default it is a free-text description and AI turns it into a structured voice profile for you — the Portal's Freeform mode. Send DESIGN_PROMPT_MODE_VERBATIM to provide the profile yourself, as key: value lines, and it is used directly with nothing interpreted or filled in — the Portal's Structured mode.

Available options:DESIGN_PROMPT_MODE_ASSISTEDDESIGN_PROMPT_MODE_VERBATIM

langCodeenum<string>

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.

Available options:EN_USZH_CNKO_KRJA_JPRU_RUAUTOIT_ITES_ESPT_BRDE_DEFR_FRAR_SAPL_PLNL_NLHI_INHE_IL

languageCodestring

The voice's language as a canonical BCP-47-shaped locale string (e.g. en-US, en-GB, vi). Set at most one of languageCode or langCode — they are two encodings of the same value. Matching is case- and separator-insensitive (en-gb, EN_GB and en-GB are equivalent); a bare language code with no region (e.g. en, pt) selects the language's default accent. Omit both fields to auto-detect the language (equivalently: langCode: "AUTO" or languageCode: "auto"). Values outside the supported catalog are rejected with INVALID_ARGUMENT. See Languages for the supported set.

previewTextstringrequired

Script for the generated voice to speak. Must result in audio that is 1-30 seconds.

The script will shape the voice that gets generated, as the model will tailor the voice to suit the content it's speaking. See Voice Design Best Practices for more details.

Response

200 - application/json

langCodeenum<string>

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.

Available options:EN_USZH_CNKO_KRJA_JPRU_RUAUTOIT_ITES_ESPT_BRDE_DEFR_FRAR_SAPL_PLNL_NLHI_INHE_IL

previewVoicesobject[]

Preview voices generated (in DRAFT status). Up to 3 voices will be generated each time you call this endpoint. Use Publish Voice to promote one to your library.

Show child attributes

voiceIdstring

The voice ID of the generated preview.

previewTextstring

The text used for the preview.

previewAudiostring

Preview audio data (base64-encoded).