curl --location 'https://api.inworld.ai/voices/v1/voices:design' \
--header "Authorization: Basic $INWORLD_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"languageCode": "en-US",
"designPrompt": "Warm, friendly, conversational voice with a subtle smile; natural pacing; clear articulation.",
"previewText": "Hey! I am here. What can I help you with today?",
"voiceDesignConfig": {
"numberOfSamples": 1
}
}'import requests
url = "https://api.inworld.ai/voices/v1/voices:design"
headers = {
"Authorization": "Basic <api-key>",
"Content-Type": "application/json"
}
payload = {
"languageCode": "en-US",
"designPrompt": "Warm, friendly, conversational voice with a subtle smile; natural pacing; clear articulation.",
"previewText": "Hey! I am here. What can I help you with today?",
"voiceDesignConfig": {
"numberOfSamples": 1
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())const url = 'https://api.inworld.ai/voices/v1/voices:design';
const response = await fetch(url, {
method: 'POST',
headers: {
'Authorization': 'Basic <api-key>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
langCode: 'EN_US',
designPrompt: 'Warm, friendly, conversational voice with a subtle smile; natural pacing; clear articulation.',
previewText: 'Hey! I am here. What can I help you with today?',
voiceDesignConfig: {
numberOfSamples: 1,
},
}),
});
const data = await response.json();
console.log(data);{
"langCode": "EN_US",
"previewVoices": [
{
"voiceId": "your_workspace_id__design-voice-38b05df9",
"previewText": "Hey! I am here. What can I help you with today? I would be happy to assist you with whatever you need. Just let me know how I can be of service.",
"previewAudio": "<base64-audio>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}Design a voice
Design a voice based on a text description. Returns preview voices that can be published using the Publish Voice endpoint.
curl --location 'https://api.inworld.ai/voices/v1/voices:design' \
--header "Authorization: Basic $INWORLD_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"languageCode": "en-US",
"designPrompt": "Warm, friendly, conversational voice with a subtle smile; natural pacing; clear articulation.",
"previewText": "Hey! I am here. What can I help you with today?",
"voiceDesignConfig": {
"numberOfSamples": 1
}
}'import requests
url = "https://api.inworld.ai/voices/v1/voices:design"
headers = {
"Authorization": "Basic <api-key>",
"Content-Type": "application/json"
}
payload = {
"languageCode": "en-US",
"designPrompt": "Warm, friendly, conversational voice with a subtle smile; natural pacing; clear articulation.",
"previewText": "Hey! I am here. What can I help you with today?",
"voiceDesignConfig": {
"numberOfSamples": 1
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())const url = 'https://api.inworld.ai/voices/v1/voices:design';
const response = await fetch(url, {
method: 'POST',
headers: {
'Authorization': 'Basic <api-key>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
langCode: 'EN_US',
designPrompt: 'Warm, friendly, conversational voice with a subtle smile; natural pacing; clear articulation.',
previewText: 'Hey! I am here. What can I help you with today?',
voiceDesignConfig: {
numberOfSamples: 1,
},
}),
});
const data = await response.json();
console.log(data);{
"langCode": "EN_US",
"previewVoices": [
{
"voiceId": "your_workspace_id__design-voice-38b05df9",
"previewText": "Hey! I am here. What can I help you with today? I would be happy to assist you with whatever you need. Just let me know how I can be of service.",
"previewAudio": "<base64-audio>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}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 withlanguageCode — 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.
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.Authorizations
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
Request message for DesignVoice.
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."
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.
Voice design configuration for generating the preview. If not provided, defaults to generating 1 sample.
Show child attributes
Show child attributes
Language code for the voice preview.
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 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.
The language code of the generated previews.
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 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
Show child attributes