VoiceService
Design a voice
Design a voice based on a text description. Returns preview voices that can be published using the Publish Voice endpoint.
/voices/v1/voices:designDesign a voice from a text description. This endpoint generates up to three preview voices that can then be published to your voice library using the Publish Voice endpoint.
For a guided workflow, see Voice Design in the docs.
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 designPrompt is a free-text description and AI turns it into a structured voice profile for you. Send designPromptMode: DESIGN_PROMPT_MODE_VERBATIM to provide the profile yourself and have it used directly — 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, anden-GBare 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>
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.
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.
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).