> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/kyutai-labs/unmute/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Cloning

> Clone voices from audio samples and manage voice donations

## Overview

The Unmute API provides endpoints for voice cloning and voice donation. Voice cloning allows you to create custom voices from audio samples, while voice donation enables users to contribute their voices to improve the service.

## Get Available Voices

Retrieve a list of pre-configured voices available for use.

<CodeGroup>
  ```bash GET /v1/voices theme={null}
  curl https://api.unmute.example/v1/voices
  ```
</CodeGroup>

### Response

Returns an array of voice objects. Each voice object contains:

<ResponseField name="name" type="string">
  The unique identifier for the voice
</ResponseField>

<ResponseField name="source" type="object">
  Information about the voice source, including path and description
</ResponseField>

<ResponseField name="instructions" type="object" optional>
  Optional instructions for using this voice
</ResponseField>

### Response Example

```json theme={null}
[
  {
    "name": "narrator-1",
    "source": {
      "source_type": "file",
      "path_on_server": "voices/narrator-1.wav",
      "description": "Professional narrator voice"
    }
  },
  {
    "name": "conversational-2",
    "source": {
      "source_type": "file",
      "path_on_server": "voices/conversational-2.wav",
      "description": "Casual conversational voice"
    }
  }
]
```

## Clone a Voice

Upload an audio file to create a custom voice clone.

<CodeGroup>
  ```bash POST /v1/voices theme={null}
  curl -X POST https://api.unmute.example/v1/voices \
    -H "Content-Type: multipart/form-data" \
    -F "file=@/path/to/voice-sample.wav"
  ```
</CodeGroup>

### Request

<ParamField body="file" type="file" required>
  Audio file containing the voice sample to clone. Supported formats include WAV, MP3, and other common audio formats.
</ParamField>

### File Size Limits

* Maximum file size is configurable (default: defined in `MAX_VOICE_FILE_SIZE_MB`)
* Files exceeding the limit will return a `413 Request Entity Too Large` error
* Minimum recommended duration: 10-30 seconds of clear speech

### Response

<ResponseField name="name" type="string" required>
  The unique identifier for the cloned voice, in the format `custom:<uuid>`. Use this name when making TTS requests.
</ResponseField>

### Response Example

```json theme={null}
{
  "name": "custom:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

### Status Codes

<ResponseField name="200" type="status code">
  Voice successfully cloned
</ResponseField>

<ResponseField name="411" type="status code">
  Content-Length header is required
</ResponseField>

<ResponseField name="413" type="status code">
  Request entity too large - file exceeds maximum size limit
</ResponseField>

## Voice Donation

Contribute your voice to help improve the Unmute service.

### Step 1: Request Verification

Initiate a voice donation by requesting a verification text to read.

<CodeGroup>
  ```bash GET /v1/voice-donation theme={null}
  curl https://api.unmute.example/v1/voice-donation
  ```
</CodeGroup>

#### Response

<ResponseField name="id" type="string" required>
  Unique identifier for this verification request. Must be included when submitting the voice donation.
</ResponseField>

<ResponseField name="text" type="string" required>
  The verification text you must read aloud. Always begins with: "I consent to my voice being used for voice cloning." followed by two randomly selected sentences.
</ResponseField>

<ResponseField name="created_at_timetamp" type="number" required>
  Unix timestamp (seconds since epoch) when the verification was created. Verifications expire after 5 minutes.
</ResponseField>

#### Response Example

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "text": "I consent to my voice being used for voice cloning. The quick brown fox jumps over the lazy dog. Technology continues to advance at a rapid pace.",
  "created_at_timetamp": 1709251200.0
}
```

### Step 2: Submit Voice Donation

Submit your voice recording along with the required metadata.

<CodeGroup>
  ```bash POST /v1/voice-donation theme={null}
  curl -X POST https://api.unmute.example/v1/voice-donation \
    -F "file=@/path/to/recording.wav" \
    -F 'metadata={"email":"user@example.com","nickname":"VoiceContributor","verification_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","license":"CC0","transcription_from_client":"I consent to..."}'
  ```
</CodeGroup>

#### Request

<ParamField body="file" type="file" required>
  Audio file containing your recording of the verification text. Must be at least 0.1 MB and no more than the configured maximum size.
</ParamField>

<ParamField body="metadata" type="string (JSON)" required>
  JSON string containing the submission metadata with the following fields:
</ParamField>

#### Metadata Fields

<ParamField body="metadata.email" type="string" required>
  Your email address. Kept private and only used if you want to withdraw your donation. Not published.
</ParamField>

<ParamField body="metadata.nickname" type="string" required>
  Public nickname to associate with your voice donation. Maximum 30 characters.
</ParamField>

<ParamField body="metadata.verification_id" type="string (UUID)" required>
  The verification ID received from the GET /v1/voice-donation endpoint.
</ParamField>

<ParamField body="metadata.license" type="string" default="CC0">
  License for the voice donation. Currently only "CC0" (Creative Commons Zero) is accepted.
</ParamField>

<ParamField body="metadata.format_version" type="string" default="1.1">
  Metadata format version. Defaults to "1.1".
</ParamField>

<ParamField body="metadata.transcription_from_client" type="string" optional>
  Optional transcription of what you recorded. Note: this is sent by the client and could be manipulated.
</ParamField>

#### Response

```json theme={null}
{}
```

An empty object is returned on successful submission.

#### Status Codes

<ResponseField name="200" type="status code">
  Voice donation successfully submitted
</ResponseField>

<ResponseField name="400" type="status code">
  Invalid request. Possible reasons:

  * Invalid JSON in metadata field
  * Invalid submission data (validation error)
  * Audio file too small (\< 0.1 MB)
  * Audio file too large (> maximum size)
  * Nickname too long (> 30 characters)
  * Verification ID not found or expired (> 5 minutes old)
</ResponseField>

<ResponseField name="411" type="status code">
  Content-Length header is required
</ResponseField>

<ResponseField name="413" type="status code">
  Request entity too large - file exceeds maximum size limit
</ResponseField>

#### Error Response Example

```json theme={null}
{
  "detail": "Verification expired after 5 minutes. Please request a new verification."
}
```

## CORS

All endpoints support CORS for the following origins:

* `http://localhost`
* `http://localhost:3000`

Credentials are allowed for cross-origin requests.

## Notes

* Voice cloning embeddings are cached for 1 hour
* Verification requests are cached for 1 hour but expire after 5 minutes for submission
* All audio processing is handled asynchronously to prevent blocking
* Voice donations are saved with both audio and metadata files for future processing


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.