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

# Introduction

> Access Audimee voice models and perform AI voice conversions

## Overview

The Audimee API lets you:

* Browse Audimee's built-in voice models and your own custom-trained voices
* Train new custom voice models from your own audio
* Submit audio files for AI voice conversion against either kind of model

Both training and conversion run asynchronously — you start the job, then poll for its status.

## Base URL

```
https://audimee.com/api/v1
```

## Authentication

All endpoints require a static API key issued by Audimee, passed as a bearer token:

```
Authorization: Bearer {token}
```

Tokens are bound to a single API client account. Unauthorized requests return `401` with one of:

* `Missing or invalid Authorization header` — header absent or not prefixed with `Bearer `
* `Invalid authorization token` — token not recognised
* `User not found` — token valid but the underlying user no longer exists

## Error responses

Every error response — across every endpoint — uses the same shape:

```json theme={null}
{ "error": "Human-readable explanation" }
```

The HTTP status code carries the category (`400` validation, `401` auth, `403` forbidden, `404` not found, `500` server error). The `error` string is the specific reason.

## Voice model types

Responses from `/voice-models` are a discriminated union on `type`:

* **`audimee`** — Built-in voices. Always available, no training. IDs are short numeric strings like `"101"`. Includes display fields (`description`, `previewUrl`, `gender`, `genres`, `pitchLow`, `pitchHigh`).
* **`custom`** — Voices you trained via `POST /voice-models`. IDs are UUIDs. Become usable for conversions once `confirmedDone: true`. Carry training state (`percentageDone`, `confirmedDone`, `failed`, `failedMessage`).

Use `?type=audimee` or `?type=custom` on `GET /voice-models` to narrow the response.

## Custom voice model lifecycle

```
POST /voice-models  →  GET /voice-models/{id}  (poll)  →  POST /conversions
```

1. **Start training.** `POST /voice-models` with `name` and `trainingAudioUrls`. The response returns immediately with `{ id, type: "custom" }`. Training is queued on the AI backend.
2. **Poll progress.** `GET /voice-models/{id}` returns the current `percentageDone` (0–100). Recommended cadence: every 10–30s — training typically takes minutes.
3. **Detect terminal state.** A model is terminal when one of:
   * `confirmedDone: true, failed: false` — ready for use in conversions
   * `failed: true` — training failed; `failedMessage` carries the reason
4. **Use it.** Pass the custom model's UUID as `voiceModelId` when calling `POST /conversions`.
5. **Delete it (optional).** `DELETE /voice-models/{id}` permanently deletes the model and its training artifacts — this is irreversible. The model must have started training on the AI backend (`percentageDone > 0`) before delete is allowed — if it hasn't, the call returns `400` and you should retry later. If training is still in progress, the delete cancels it first.

## Conversion lifecycle

```
POST /conversions  →  GET /conversions/{id}  (poll)  →  download output URLs
```

1. **Start the conversion.** `POST /conversions` with `voiceModelId` and `inputFileUrl`. Optional knobs: `conversionStrength`, `pitchShift`, `sampleRateHz`. Response: `{ id }`.
2. **Poll progress.** `GET /conversions/{id}` returns `percentageDone` and `confirmedDone`. Recommended cadence: every 5–15s — conversions are typically faster than training.
3. **Detect terminal state.** `confirmedDone: true` (success) or `failed: true` (failure).
4. **Download the output.** When `confirmedDone` is `true`, the `outputFilePlayUrl` (MP3, for streaming) and `outputFileDownloadUrl` (WAV when available, MP3 otherwise) are usable signed URLs. The URLs are present in the response from the moment the conversion is created, but they don't resolve to audio until the job is done — gate access on `confirmedDone`, not on URL contents.

## Plan limits

API client accounts may have plan-driven limits:

* **Maximum concurrent custom models** — when reached, `POST /voice-models` returns `400` with `Custom model limit reached (max N)`.
* **Maximum combined training audio duration per model** — default 30 minutes. When exceeded, `POST /voice-models` returns `400` with the actual vs. allowed seconds.

Audio files passed via `trainingAudioUrls` and `inputFileUrl` must be publicly reachable URLs — the server downloads them server-side. The host doesn't need to be Audimee's, but it does need to be available for the duration of the API call.

## Quick example — convert with a built-in voice

```bash theme={null}
# 1. Pick a built-in voice
curl https://audimee.com/api/v1/voice-models?type=audimee \
  -H "Authorization: Bearer {token}"

# 2. Start a conversion
curl -X POST https://audimee.com/api/v1/conversions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "voiceModelId": "101",
    "inputFileUrl": "https://example.com/audio/my-recording.wav",
    "conversionStrength": 0.7
  }'

# 3. Poll until confirmedDone is true
curl https://audimee.com/api/v1/conversions/{id} \
  -H "Authorization: Bearer {token}"
```

## Quick example — train and use a custom voice

```bash theme={null}
# 1. Start training a custom model
curl -X POST https://audimee.com/api/v1/voice-models \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My band lead",
    "trainingAudioUrls": [
      "https://example.com/audio/take-1.wav",
      "https://example.com/audio/take-2.wav"
    ]
  }'

# 2. Poll the model until confirmedDone is true
curl https://audimee.com/api/v1/voice-models/{id} \
  -H "Authorization: Bearer {token}"

# 3. Use it the same way as a built-in voice
curl -X POST https://audimee.com/api/v1/conversions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "voiceModelId": "{custom-model-uuid}",
    "inputFileUrl": "https://example.com/audio/my-recording.wav"
  }'
```