Skip to main content
POST
cURL
Design 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-15 seconds long (~50-200 characters in English).

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-GBEN_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.

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.

Body

application/json

Request message for DesignVoice.

designPrompt
string
required

Text description of the desired voice. Must be in English and between 30 and 250 characters. 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."

previewText
string
required

Script for the generated voice to speak. Must result in audio that is 1-15 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.

voiceDesignConfig
object

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

langCode
enum<string>

Language code for the voice preview.

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

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.

Response

A successful response.

Response message for DesignVoice.

langCode
enum<string>

The language code of the generated previews.

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
previewVoices
object[]

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.