Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Generate speech audio with text-to-speech (TTS) or speech-to-speech (STS).
mp3 from either a text script or an
existing audio file. It uses the AdSkull voice library and your custom
cloned voices.
| Method | Endpoint | Purpose |
|---|---|---|
POST | /v1/voice-generations | Create a TTS or STS job. |
GET | /v1/voice-generations | List recent voice jobs. |
GET | /v1/voice-generations/{job_id} | Get one voice job. |
GET | /v1/voices | List library voices (voice_id, name, locale, preview_url). |
GET | /v1/custom-voices | List your cloned voices. |
| Mode | What it does | Required fields |
|---|---|---|
tts | Text-to-Speech. Generates audio from a script. | voice_id, text |
sts | Speech-to-Speech. Re-voices an existing audio file. | voice_id, audio_url |
| Field | Type | Required | Notes |
|---|---|---|---|
voice_id | string | Yes | Library voice ID (e.g. ahmed) or one of your custom voice IDs. |
mode | string | No | tts (default) or sts. Anything else is rejected. |
text | string | Yes when mode=tts | Up to 8192 characters. Estimated duration = len(text) / 12 seconds. |
audio_url | string | Yes when mode=sts | Hosted audio URL — mp3/wav/m4a/ogg/webm, up to 50 MB. Upload local files via POST /v1/assets first. |
Idempotency-Key is required on every POST /v1/voice-generations.tts, or
measured from the uploaded audio for sts.curl https://api.adskull.io/v1/voice-generations \
-H "Authorization: Bearer $ADSKULL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: voice-tts-001" \
-d '{
"voice_id": "ahmed",
"mode": "tts",
"text": "Welcome to AdSkull. Let us turn your idea into a finished ad in seconds."
}'
# 1) Upload the source recording
curl https://api.adskull.io/v1/assets \
-H "Authorization: Bearer $ADSKULL_API_KEY" \
-F asset_type=audio \
-F file=@./voice-memo.mp3
# 2) Re-voice it
curl https://api.adskull.io/v1/voice-generations \
-H "Authorization: Bearer $ADSKULL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: voice-sts-001" \
-d '{
"voice_id": "ahmed",
"mode": "sts",
"audio_url": "https://cdn.adskull.io/uploads/..."
}'
{
"id": "job_01HXVO...",
"object": "voice_generation_job",
"status": "completed",
"credits_reserved": 4,
"credits_used": 4,
"duration_seconds": 17.4,
"completed_at": "2026-05-17T12:01:02Z",
"assets": [
{
"id": "asset_01HX...",
"type": "audio",
"url": "https://cdn.adskull.io/generated/voiceover.mp3",
"mime_type": "audio/mpeg",
"duration_seconds": 17.4,
"expires_at": "2026-05-18T12:01:02Z"
}
]
}
| HTTP | Code | When it happens |
|---|---|---|
| 400 | invalid_request | Missing field for the chosen mode, unknown voice, unsupported audio format. |
| 401 | unauthorized | API key missing or invalid. |
| 402 | insufficient_credits | Not enough credits to cover the estimated duration. |
| 413 | payload_too_large | Uploaded audio > 50 MB. |
| 422 | content_policy_violation | Text or audio not allowed. |
| 429 | rate_limited | Too many requests. |
| 503 | temporarily_unavailable | Provider capacity temporarily unavailable. |