> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adskull.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Voices

> Clone a voice from audio or design a voice from a description.

Custom voices are quota-based. Creating a cloned or designed voice uses monthly custom voice creation quota, not per-call AI credits in the current product model.

## Endpoints

| Method   | Endpoint                       | Purpose                                        |
| -------- | ------------------------------ | ---------------------------------------------- |
| `GET`    | `/v1/custom-voices`            | List custom voices and quota state.            |
| `POST`   | `/v1/custom-voices/clone`      | Clone a custom voice from an audio URL.        |
| `POST`   | `/v1/custom-voices/design`     | Design a custom voice from a text description. |
| `DELETE` | `/v1/custom-voices/{voice_id}` | Delete a custom voice.                         |

## Clone Parameters

| Field       | Type   | Required | Notes                              |
| ----------- | ------ | -------- | ---------------------------------- |
| `name`      | string | Yes      | Display name for the custom voice. |
| `audio_url` | string | Yes      | Uploaded or public audio URL.      |

## Design Parameters

| Field         | Type   | Required | Notes                                                 |
| ------------- | ------ | -------- | ----------------------------------------------------- |
| `name`        | string | Yes      | Display name for the custom voice.                    |
| `description` | string | No       | Voice style, accent, tone, and pacing.                |
| `gender`      | string | No       | Optional gender hint when no description is provided. |
| `age`         | string | No       | Optional age hint when no description is provided.    |
| `accent`      | string | No       | Optional accent hint when no description is provided. |

## Clone Request

```bash theme={"theme":"github-dark"}
curl https://api.adskull.io/v1/custom-voices/clone \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: custom-voice-001" \
  -d '{
    "name": "Founder Voice",
    "audio_url": "https://cdn.adskull.io/uploads/sample-voice.mp3"
  }'
```

## Design Request

```bash theme={"theme":"github-dark"}
curl https://api.adskull.io/v1/custom-voices/design \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: custom-voice-002" \
  -d '{
    "name": "Calm Product Educator",
    "description": "Warm, confident, clear pacing, light American accent, premium skincare educator style"
  }'
```

## Success Response

```json theme={"theme":"github-dark"}
{
  "id": "voice_01HX...",
  "object": "custom_voice",
  "name": "Founder Voice",
  "status": "ready",
  "voice_type": "clone",
  "description": "Cloned from public API audio URL",
  "preview_url": "https://cdn.adskull.io/generated/preview.mp3",
  "created_at": "2026-05-17T12:00:00Z"
}
```

## Possible Errors

| HTTP | Code                     | When it happens                                                                         |
| ---: | ------------------------ | --------------------------------------------------------------------------------------- |
|  400 | `invalid_request`        | Missing name, invalid audio URL, or invalid voice design fields.                        |
|  401 | `unauthorized`           | API key is missing or invalid.                                                          |
|  403 | `forbidden`              | Key lacks `voices:write`, account is not Creator or higher, or deletion is not allowed. |
|  409 | `quota_exhausted`        | Monthly custom voice creation quota is exhausted.                                       |
|  409 | `voice_limit_reached`    | Account already has the maximum simultaneous custom voices.                             |
|  415 | `unsupported_media_type` | Audio input type is not accepted.                                                       |
|  429 | `rate_limited`           | Key, account, or IP exceeded rate limits.                                               |