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

# Clone a voice

`POST /voices/v1/voices:clone`

Clone a voice from audio samples.

## Request body

- VoiceServiceCloneVoiceBody — Request message for CloneVoice custom method.
  - `displayName` string, required — The human-readable name shown anywhere the voice is listed or selected. Keep it short and distinctive so users can find it easily.
  - `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.
  - `voiceSamples` V1VoiceSample[], 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-15 sec audio clip; longer clips will be cutoff at 15sec, which can affect quality. See [Voice Cloning Best Practices](https://docs.inworld.ai/tts/best-practices/voice-cloning) for guidance on how to generate a high-quality voice clone.
    - `audioData` string, byte, required — Binary audio data for the sample (base64-encoded in JSON). Supports WAV and MP3 formats.
    - `transcription` string — Optional user-provided transcription of the audio sample. If one is not provided, the transcription will be generated automatically.
  - `description` string — Longer blurb that explains the voice's tone, accent, use cases, or other relevant attributes. Helpful for search and selection.
  - `tags` string[] — 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](/api-reference/voiceAPI/voiceservice/update-voice) after cloning.
  - `audioProcessingConfig` V1AudioProcessingConfig — Audio processing config for voice cloning.
    - `removeBackgroundNoise` boolean — 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`

A successful response.

- V1CloneVoiceResponse — Response message for CloneVoice custom method.
  - `voice` Inworldvoicev1Voice — Voice resource representing a voice configuration.
    - `voiceId` string — Voice ID. SYSTEM voices use a simple name (e.g. `Alex`); IVC voices are workspace-prefixed (`{workspace}__{voice}`).
    - `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 — 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.
    - `displayName` string — The human-readable name shown anywhere the voice is listed or selected.
    - `description` string — Longer blurb that explains the voice's tone, accent, use cases, or other relevant attributes.
    - `tags` string[] — Free-form labels for filtering, grouping, and discovery (e.g. `british`, `calm`).
    - `name` string — Resource name. Format: `workspaces/{workspace}/voices/{voice}`.
    - `source` 'SYSTEM' | 'IVC' | 'PVC' — Origin of the voice: - `SYSTEM`: Built-in voice provided by Inworld, visible to all workspaces. - `IVC`: Voice cloned from audio or created via Voice Design — owned by your workspace only. - `PVC`: Professional Voice Clone.
    - `gender` 'male' | 'female' | 'neutral' | '' — Voice gender (`male`, `female`, `neutral`). Empty string if unspecified. Voices with no gender are excluded when filtering with an explicit `gender =` predicate.
    - `ageGroup` 'young' | 'middle_aged' | 'elderly' | '' — Age group of the voice (`young`, `middle_aged`, `elderly`). Empty string if unspecified.
    - `categories` string[] — Use-case categories the voice belongs to. Filterable with the `:` (has) operator. Supported values: `companions`, `enterprise`, `education_training`, `developer_assistants`, `healthcare`, `interactive_media`.
    - `promptLanguages` string[] — Languages the voice can handle, in BCP-47 format (e.g. `en-US`). May differ from `langCode` for multilingual voices.
  - `audioSamplesValidated` V1AudioSampleValidated[] — The list of validated samples.
    - `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.
    - `warnings` AudioSampleValidatedWarning[] — The list of detected warnings for this sample.
      - `text` string — The warning message.
    - `errors` AudioSampleValidatedError[] — The list of detected errors for this sample.
      - `text` string — The error message.
    - `transcription` string — Transcription of the processed audio sample.
    - `audioData` string, byte — The processed audio data (base64-encoded). This is the audio after processing (e.g., background noise removal if enabled), not the originally uploaded audio.

## 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/versions/e79009799a0d/schema)