Introduction

​

Overview

• 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

​

Base URL

https://audimee.com/api/v1

​

Authentication

Authorization: Bearer {token}

• 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

{ "error": "Human-readable explanation" }

​

Voice model types

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

​

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

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

​

Quick example — convert with a built-in voice

# 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

# 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"
  }'