> ## 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.

# Voiceover

> Generate speech audio with text-to-speech (TTS) or speech-to-speech (STS).

The voiceover endpoint produces an `mp3` from either a text script or an
existing audio file. It uses the AdSkull voice library and your custom
cloned voices.

## Endpoints

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

## Modes

| 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` |

## Create Parameters

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

<Note>
  `Idempotency-Key` is **required** on every `POST /v1/voice-generations`.
</Note>

## Pricing

* 2 credits per 10 seconds, rounded up to the next 10 seconds.
* Minimum 2 credits per request.
* Duration is estimated from text length (12 chars / second) for `tts`, or
  measured from the uploaded audio for `sts`.

## Example: TTS

```bash theme={"theme":"github-dark"}
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."
  }'
```

## Example: STS (re-voice an existing recording)

```bash theme={"theme":"github-dark"}
# 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/..."
  }'
```

## Completed Response

```json theme={"theme":"github-dark"}
{
  "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"
    }
  ]
}
```

## Possible Errors

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