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.

GET /v1/voices

curl https://api.unmute.example/v1/voices

Response

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

name · string

The unique identifier for the voice

source · object

Information about the voice source, including path and description

instructions · object

Optional instructions for using this voice

Response Example

[
  {
    "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.

POST /v1/voices

curl -X POST https://api.unmute.example/v1/voices \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/voice-sample.wav"

Request

file · file · required

Audio file containing the voice sample to clone. Supported formats include WAV, MP3, and other common audio formats.

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

name · string · required

The unique identifier for the cloned voice, in the format custom:<uuid>. Use this name when making TTS requests.

Response Example

{
  "name": "custom:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Status Codes

200 · status code

Voice successfully cloned

411 · status code

Content-Length header is required

413 · status code

Request entity too large - file exceeds maximum size limit

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.

GET /v1/voice-donation

curl https://api.unmute.example/v1/voice-donation

Response

id · string · required

Unique identifier for this verification request. Must be included when submitting the voice donation.

text · 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.

created_at_timetamp · number · required

Unix timestamp (seconds since epoch) when the verification was created. Verifications expire after 5 minutes.

Response Example

{
  "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.

POST /v1/voice-donation

curl -X POST https://api.unmute.example/v1/voice-donation \
  -F "file=@/path/to/recording.wav" \
  -F 'metadata={"email":"[e-mail]","nickname":"VoiceContributor","verification_id":"b2c3d4e5-f6a7-8901-bcde-f12345678901","license":"CC0","transcription_from_client":"I consent to..."}'

Request

file · 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.

metadata · string (JSON) · required

JSON string containing the submission metadata with the following fields:

Metadata Fields

metadata.email · string · required

Your email address. Kept private and only used if you want to withdraw your donation. Not published.

metadata.nickname · string · required

Public nickname to associate with your voice donation. Maximum 30 characters.

metadata.verification_id · string (UUID) · required

The verification ID received from the GET /v1/voice-donation endpoint.

metadata.license · string · default: "CC0"

License for the voice donation. Currently only “CC0” (Creative Commons Zero) is accepted.

metadata.format_version · string · default: "1.1"

Metadata format version. Defaults to “1.1”.

metadata.transcription_from_client · string

Optional transcription of what you recorded. Note: this is sent by the client and could be manipulated.

Response

{}

An empty object is returned on successful submission.

Status Codes

200 · status code

Voice donation successfully submitted

400 · 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)

411 · status code

Content-Length header is required

413 · status code

Request entity too large - file exceeds maximum size limit

Error Response Example

{
  "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