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