> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inworld.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Design a voice

> Design a voice based on a text description. Returns preview voices that can be published using the Publish Voice endpoint.

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](https://docs.inworld.ai/api-reference/voiceAPI/voiceservice/publish-voice.md).

For a guided workflow, see [Voice Design](https://docs.inworld.ai/tts/voice-design.md).

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

<Note>
**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](https://docs.inworld.ai/tts/best-practices/voice-design.md).
</Note>

## 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](https://docs.inworld.ai/tts/capabilities/multilingual.md) for the supported languages.

<Note>
**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.
</Note>

<RequestField body="languageCode" type="string">
Canonical locale string, e.g. `en-US`, `en-GB`, `vi`. See [Choosing the voice's language](#choosing-the-voices-language) above.
</RequestField>

## API reference

**Endpoint:** `POST https://api.inworld.ai/voices/v1/voices:design`

### Authorization

- `Authorization` (string; required) — Your [API key](../../../api-reference/introduction). 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](../../../developer-tools/inworld-cli): `inworld workspace add-key`.

### Request body

Content type: `application/json`

- `voiceDesignConfig` (object) — Voice design configuration for generating the preview. If not provided, defaults to generating 1 sample.
  - `numberOfSamples` (integer) — Number of voice samples to generate. Must be between 1 and 3. Default is 1 if not provided.
- `designPrompt` (string; required) — 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](https://docs.inworld.ai/tts/best-practices/voice-design.md) for more details.
  
  Example: "A middle-aged male voice with a clear British accent speaking at a steady pace and with a neutral tone."
- `designPromptMode` (enum<string>; default: "DESIGN_PROMPT_MODE_ASSISTED"; options: "DESIGN_PROMPT_MODE_ASSISTED", "DESIGN_PROMPT_MODE_VERBATIM") — 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.
- `langCode` (enum<string>; 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") — 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.
- `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](https://docs.inworld.ai/tts/capabilities/multilingual.md) for the supported set.
- `previewText` (string; required) — 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](https://docs.inworld.ai/tts/best-practices/voice-design.md) for more details.

#### Request example

```json
{
  "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? I would be happy to assist you with whatever you need. Just let me know how I can be of service.",
  "voiceDesignConfig": {
    "numberOfSamples": 1
  }
}
```

### Response

Status: `200`. Content type: `application/json`.

- `langCode` (enum<string>; 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") — 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.
- `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.
  - `voiceId` (string) — The voice ID of the generated preview.
  - `previewText` (string) — The text used for the preview.
  - `previewAudio` (string) — Preview audio data (base64-encoded).

### Response examples

#### 200: success

```json
{
  "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>"
    }
  ]
}
```

#### default: default_response

```json
{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}
```

### Code examples

#### cURL

```bash
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
  }
}'
```

#### Python

```python
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())
```

#### JavaScript

```javascript
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);
```

#### Inworld CLI

```bash
inworld tts design \
  "A warm, deep narrator voice with a subtle British accent" \
  --script "Welcome. Let me tell you a story from a world beyond imagination." \
  --lang EN_US \
  --count 3 \
  --json
```

#### cURL (structured profile)

```bash
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",
  "designPromptMode": "DESIGN_PROMPT_MODE_VERBATIM",
  "designPrompt": "dialect: west country english\ngender: male\nage: adult\nemotion: amused and lighthearted\ntone: performative and theatrical\npitch: medium-low male pitch with varied intonation for emphasis\nvolume: loud and projecting\nspeed: slow and deliberate, with dramatic pauses\nclarity: moderate, some words are slurred or mumbled\nfluency: fluent but interrupted by laughter\npersonality: playful, confident, and a bit mischievous\ntexture: harsh and raspy, with a gravelly, weathered quality\nenvironment: large, reverberant indoor space, like a hall or chamber",
  "previewText": "Batten down the hatches, lads. There be a storm off the starboard bow.",
  "voiceDesignConfig": {
    "numberOfSamples": 3
  }
}'
```