---
title: "Design a voice"
method: POST
path: "/voices/v1/voices:design"
tags: ["VoiceService"]
---

# Design a voice

`POST /voices/v1/voices:design`

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

## Request body

- VoiceServiceDesignVoiceBody — Request message for DesignVoice.
  - `voiceDesignConfig` V1VoiceDesignConfig — Voice design configuration for generating voices from a design prompt.
    - `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 between 30 and 250 characters. For best results, include age, gender, accent, pitch, pace, and tone. See [Voice Design Best Practices](/tts/best-practices/voice-design) for more details. Example: "A middle-aged male voice with a clear British accent speaking at a steady pace and with a neutral tone."
  - `langCode` '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](/tts/capabilities/multilingual) for the supported set.
  - `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](/tts/best-practices/voice-design) for more details.

## Response `200`

A successful response.

- V1DesignVoiceResponse — Response message for DesignVoice.
  - `langCode` '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` V1PreviewVoice[] — 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, byte — Preview audio data (base64-encoded).

## Other responses

- `default` — An unexpected error response.

---

[API](https://skmtc.net/inworld/apis/inworld-text-to-speech-api.md) · [All operations](https://skmtc.net/inworld/apis/inworld-text-to-speech-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/inworld/inworld-text-to-speech-api/revisions/e79009799a0d/schema)