VoiceService

Clone a voice

Inworld Voice API reference: create an instant voice clone (IVC) from short audio samples to use with Inworld TTS.

POST/voices/v1/voices:clone

Short URL path: You can omit /workspaces/{workspace} from the path. When omitted, the workspace comes from your API key. The previous full URL /voices/v1/workspaces/{workspace}/voices:clone continues to be supported.

Setting gender, ageGroup, and categories. You cannot set these when cloning. The API silently ignores them here, including values placed in tags, and returns them empty. Set them after cloning with UpdateVoice.

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 clone a British-accented voice, send "en-GB"; for Australian, "en-AU".
Auto-detect — omit the field (or send "auto") to detect the language from the audio samples.
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>

Authorizations

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.

Body

application/json

displayNamestringrequired

The human-readable name shown anywhere the voice is listed or selected. Keep it short and distinctive so users can find it easily.

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.

voiceSamplesobject[]required

Voice samples used for cloning. For best results, provide clear audio and avoid speaking in multiple languages, whispering, or making non-verbal sounds like coughing. Instant voice cloning works best with a 10-30 sec audio clip; longer clips will be cut off at 30 sec, which can affect quality. See Voice Cloning Best Practices for guidance on how to generate a high-quality voice clone.

Show child attributes

audioDatastringrequired

Binary audio data for the sample (base64-encoded in JSON). Supports WAV and MP3 formats.

transcriptionstring

Optional user-provided transcription of the audio sample. If one is not provided, the transcription will be generated automatically.

descriptionstring

Longer blurb that explains the voice's tone, accent, use cases, or other relevant attributes. Helpful for search and selection.

tagsstring[]

Free-form labels for filtering, grouping, and discovery (e.g. ["british", "calm"]). This is not where gender or age go — those are separate fields set via UpdateVoice after cloning.

audioProcessingConfigobject

Audio processing config for voice cloning.

Show child attributes

removeBackgroundNoiseboolean

Whether to remove background noise from the samples. If true, an audio isolation model will be used to clean the samples. Note: This can degrade quality if samples are already clean.

Response

200 - application/json

voiceobject

Voice resource representing a voice configuration.

Show child attributes

voiceIdstring

Voice ID. SYSTEM voices use a simple name (e.g. Alex); IVC voices are workspace-prefixed ({workspace}__{voice}).

langCodeenum<string>

Primary language of the voice in upper-snake format (e.g. EN_US). Note that when filtering via lang_code, you can pass BCP-47 (en-US), underscore form (en_US), or a language prefix (en) — but the response always returns upper-snake.

Available options:EN_USZH_CNKO_KRJA_JPRU_RUAUTOIT_ITES_ESPT_BRDE_DEFR_FRAR_SAPL_PLNL_NLHI_INHE_IL

languageCodestring

Canonical wire form of the voice's primary language as a single string (e.g. en-US, es-MX, vi). Populated on every read alongside the legacy langCode enum. Immutable after creation.

displayNamestring

The human-readable name shown anywhere the voice is listed or selected.

descriptionstring

Longer blurb that explains the voice's tone, accent, use cases, or other relevant attributes.

tagsstring[]

Free-form labels for filtering, grouping, and discovery (e.g. british, calm).

namestring

Resource identifier. Workspace voices use workspaces/{workspace}/voices/{voice}; system and shared voices may use a bare identifier. For synthesis and audio previews, use voiceId unchanged instead of constructing a resource path.

sourceenum<string>

Voice provenance: SYSTEM (Inworld system voice), IVC (instant voice clone), TVD (voice design), PVC (professional or supplied custom voice), or OTHER. Treat provenance separately from community-sharing and ownership metadata.

Available options:SYSTEMIVCTVDPVCOTHER

genderenum<string>

Voice gender (male, female, neutral). Empty string if unspecified. Voices with no gender are excluded when filtering with an explicit gender = predicate.

Available options:malefemaleneutral

ageGroupenum<string>

Age group of the voice (young, middle_aged, elderly). Empty string if unspecified.

Available options:youngmiddle_agedelderly

categoriesenum<string>[]

Use-case categories the voice belongs to. Filterable with the : (has) operator.

Supported values: companions, enterprise, education_training, developer_assistants, healthcare, interactive_media.

promptLanguagesstring[]

Every language the voice can speak, in BCP-47 format (e.g. en-US): its source language first, then each language it has been localized to. A voice without localizations has one entry; a voice whose language is detected automatically has none. Returned by both listing and getting a voice.

ownedboolean

For a community voice result, whether the calling workspace owns the voice. Interpret alongside community-sharing metadata; this field is not a general test for whether synthesis is permitted.

audioSamplesValidatedobject[]

The list of validated samples.

Show child attributes

langCodeenum<string>

Available options:EN_USZH_CNKO_KRJA_JPRU_RUAUTOIT_ITES_ESPT_BRDE_DEFR_FRAR_SAPL_PLNL_NLHI_INHE_IL

warningsobject[]

The list of detected warnings for this sample.

Show child attributes

textstring

The warning message.

errorsobject[]

The list of detected errors for this sample.

Show child attributes

textstring

The error message.

transcriptionstring

Transcription of the processed audio sample. This field is used only by the legacy inworld-tts-1.5-max and inworld-tts-1.5-mini voice-cloning flows, which clone from both the processed audio and its transcription. TTS-2 voice cloning does not use this field.

audioDatastring

The processed audio data (base64-encoded) returned for transcription review. It contains up to 15 seconds of audio, so it may be shorter than the uploaded sample. A truncated value does not mean the uploaded sample was truncated for TTS-2 cloning.

Clone a voice

curl --location 'https://api.inworld.ai/voices/v1/voices:clone' \
--header "Authorization: Basic $INWORLD_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "displayName": "my_voice_clone_demo",
  "languageCode": "en-US",
  "voiceSamples": [
    {
      "audioData": "<base64-audio-data>",
      "transcription": "Hello! This is a short voice sample for cloning."
    }
  ],
  "description": "Voice clone created from provided WAV sample.",
  "tags": ["demo", "clone"],
  "audioProcessingConfig": {
    "removeBackgroundNoise": true
  }
}'

success

{
  "audioSamplesValidated": [
    {
      "audioData": "<base64-wav-bytes>",
      "errors": [],
      "langCode": "EN_US",
      "transcription": "Hello! This is a short voice sample for cloning.",
      "warnings": []
    }
  ],
  "voice": {
    "voiceId": "your_workspace_id__my_voice_clone_demo_20260218_223134z",
    "langCode": "EN_US",
    "displayName": "my_voice_clone_demo",
    "description": "Voice clone created from provided WAV sample.",
    "tags": [
      "demo",
      "clone"
    ],
    "name": "workspaces/your_workspace_id/voices/my_voice_clone_demo_20260218_223134z",
    "source": "IVC"
  }
}