Aller au contenu
API Reference · v1

Build with Audexum.

REST API. Bearer auth. JSON in, WAV/MP3/OGG/Opus out. Streaming and webhooks included.

Authentification

Générez une clé API depuis les paramètres développeur. Envoyez-la comme jeton Bearer dans chaque requête.

http
Authorization: Bearer sk_live_•••••••••••••••••••••••••••••••••

POST/api/synthesize

Générez de l’audio à partir de texte. Renvoie audio/wav par défaut (44.1 kHz, 16 bits PCM, mono). Utilisez format pour MP3/OGG/Opus, ou stream=true pour un streaming par blocs à faible latence.

curl
# The shortest call there is. No backend named, so you get
# V3 Expressive on the Atlas voice — our most expressive engine.
curl -X POST https://audexum.com/api/synthesize \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world"}' \
  --output hello.wav

# V2 Multilingual, where speed and steps apply and 32 languages are available.
curl -X POST https://audexum.com/api/synthesize \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello world",
    "backend": "v2",
    "voice": "M1",
    "lang": "en",
    "speed": 1.05,
    "steps": 8
  }' \
  --output hello.wav

Corps de la requête

ChampSaisissezPar défautRemarques
textstringpar défaut requiredUp to ~5,000 characters per call.
voiceper tier (see Voice tiers)par défaut AtlasVoice ids are tier-specific. The default follows backend.
langen, bg, ko, ja, ar, de, …par défaut en33 supported. See /api/voices.
speed0.5–2.0par défaut 1.05 (V1 and V3: 1.0)Speaking pace, on every engine except V4. Pitch is kept.
steps4–16par défaut 8Diffusion steps. More = higher quality, slower.
formatwav | mp3 | ogg | opuspar défaut wavOutput format. Quota is identical across formats.
streambooleanpar défaut falseStream chunked WAV. Only format=wav, and V1/V2 only. V3 Expressive returns the whole file and ignores stream.
backendv3 | v2 | v1par défaut v3Voice tier. Omit it and you get V3 Expressive. See Voice tiers below.
instructstringpar défaut ""V3 only. Natural-language style/emotion, e.g. "warm and slow". Ignored by V1/V2.

Niveaux de voix

Choisissez un niveau avec backend. Chaque niveau possède ses propres voix et un multiplicateur de crédits par caractère. L’envoi d’une voix inconnue pour un niveau renvoie une erreur 400.

Omettez backend et le niveau est déduit : une voix V2 (F1..F5, M1..M5) vous permet de rester sur V2 Multilingual, une voix V3 sélectionne V3 Expressive, et ne nommer aucune voix vous donne V3 Expressive surAtlas. Les intégrations existantes qui envoient uniquement unevoix ne sont pas affectées et conservent la facturation au multiplicateur de leur niveau.

backendniveaucoûtvoix
v1V1 Instant : rapide, conçu d’abord pour l’anglais1×Voir /api/voices
v2V2 Multilingual : 32 langues, dont le bulgare1.5×F1..F5, M1..M5
v3V3 Expressive : la plus expressive, avec émotion et style2×Atlas, Reid, Sage, Kai, Cole, Ivy, Mira, Elle, Nova
curl
# V3 Expressive — most expressive tier, with an optional style prompt
curl -X POST https://audexum.com/api/synthesize \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "We shipped it. Finally.",
    "backend": "v3",
    "voice": "Atlas",
    "instruct": "warm, relieved, unhurried"
  }' \
  --output ultra.wav

En-têtes de réponse

ChampSaisissezPar défautRemarques
Content-Typestringpar défaut —audio/wav · audio/mpeg · audio/ogg · audio/opus
X-Gen-Time-Msintpar défaut —Wall-clock generation time, ms.
X-Audio-Duration-Sfloatpar défaut —Output audio duration, seconds.
X-RTFfloatpar défaut —Audio / generation ratio. >1 = faster than real-time.
X-Formatstringpar défaut —Echo of requested format.
X-Stream1par défaut —Present when stream=true; body is concatenated WAV chunks.

Formats de sortie (OGG / Opus / MP3)

Ajoutez "format": "ogg" (ou mp3 / opus) pour obtenir une réponse transcodée. Le quota est identique quel que soit le format. Le filigrane AudioSeal résiste à l’encodage MP3.

curl
# OGG/Opus — smallest file size, best for streaming/web
curl -X POST https://audexum.com/api/synthesize \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "voice": "M1", "lang": "en", "format": "ogg"}' \
  --output hello.ogg

# MP3 — maximum compatibility
curl -X POST https://audexum.com/api/synthesize \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "voice": "M1", "lang": "en", "format": "mp3"}' \
  --output hello.mp3
python
import requests

r = requests.post(
    "https://audexum.com/api/synthesize",
    headers={"Authorization": "Bearer sk_live_..."},
    json={"text": "Hello world", "voice": "M1", "lang": "en", "format": "ogg"},
)
r.raise_for_status()
with open("hello.ogg", "wb") as f:
    f.write(r.content)
# Content-Type: audio/ogg
formatContent-TypeCodec
wavaudio/wavPCM 16-bit, 44.1 kHz (sans transcodage)
mp3audio/mpeglibmp3lame VBR ~192 kbps
oggaudio/ogglibopus 96 kbps, 48 kHz
opusaudio/opuslibopus 96 kbps, 48 kHz (conteneur Ogg)

TTS en streaming

Ajoutez "stream": true pour recevoir l’audio au fil de sa génération. La réponse est un flux à transfert par blocs contenant des fichiers WAV concaténés. Chaque bloc est un fichier WAV complet et valide (en-tête RIFF de 44 octets + PCM), ce qui vous permet de lancer immédiatement la lecture. Le quota est réservé pour l’intégralité du texte dès le départ, exactement comme pour un appel sans streaming. Le streaming nécessite format=wav (par défaut).

curl
curl -X POST https://audexum.com/api/synthesize \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Sentence one. Sentence two. Sentence three.", "voice": "M1", "lang": "en", "stream": true}' \
  --no-buffer --output - | ffplay -nodisp -i pipe:0
python
import requests

with requests.post(
    "https://audexum.com/api/synthesize",
    headers={"Authorization": "Bearer sk_live_..."},
    json={
        "text": "First sentence. Second sentence. Third one.",
        "voice": "M1",
        "lang": "en",
        "stream": True,
    },
    stream=True,
) as r:
    r.raise_for_status()
    with open("streamed.wav", "wb") as f:
        for chunk in r.iter_content(chunk_size=None):
            f.write(chunk)
# Each yielded chunk is a standalone WAV file (header + PCM).
# Concatenating them produces valid gapless audio.
Remarques sur le streaming : le texte est découpé aux limites des phrases (~1–3 phrases par bloc). Le format doit être wav. La latence du premier bloc est enregistrée côté serveur. L’en-tête de réponse X-Stream: 1 confirme le mode streaming.

POST/api/transcribe

Transcrivez de la parole en texte. Envoyez l’audio sous forme de multipart/form-data. Nécessite une clé sans restrictions (les clés de widget sont limitées à /api/synthesize). Facturé à 200 crédits par minute d’audio.

curl
curl -X POST https://audexum.com/api/transcribe \
  -H "Authorization: Bearer sk_live_..." \
  -F "[email protected]" \
  -F "timestamps=true"

Champs du formulaire

ChampRemarques
audioObligatoire. Un fichier audio/*, jusqu’à 25 Mo et 600 secondes.
timestampsBooléen facultatif. Inclut les minutages de début et de fin de chaque segment.
vocabularyFacultatif. Jusqu’à 2000 caractères de termes métier pour orienter la reconnaissance.
clean / modeFacultatif. Post-traiter la transcription (nettoyage, e-mail, professionnel, puces, concis).

Réponse

json
{
  "text": "Full transcript…",
  "duration_s": 12.3,
  "transcribe_ms": 480,
  "segments": [{ "start": 0.0, "end": 3.2, "text": "…" }],
  "raw_text": "…",   // present only when a clean/transform mode was requested
  "mode": "clean"
}

POST/v1/audio/transcriptions

Reconnaissance vocale compatible OpenAI. Un outil permettant de modifier son URL de base OpenAI peut utiliser Audexum en la définissant sur https://audexum.com/v1, sans modification du code. Il utilise le même moteur et la même facturation que /api/transcribe: 200 crédits par minute d’audio. Envoyez multipart/form-data.

L’authentification est Authorization: Bearer sk_live_…Créez la clé dans les paramètres développeur (connexion requise). Utilisez une clé sk_live_ clé ; les clés widget restrictions renvoient 403 ici.

curl
curl https://audexum.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk_live_..." \
  -F [email protected] \
  -F model=whisper-1 \
  -F language=bg \
  -F response_format=json
# {"text": "…"}
python
from openai import OpenAI

client = OpenAI(api_key="sk_live_...", base_url="https://audexum.com/v1")

with open("recording.mp3", "rb") as f:
    result = client.audio.transcriptions.create(
        model="whisper-1",
        file=f,
        language="bg",   # optional; omit to auto-detect
    )
print(result.text)

Champs du formulaire

ChampSaisissezPar défautRemarques
filefilepar défaut requiredUp to 25 MB and 600 seconds. Content-Type audio/*, video/webm, video/ogg or application/octet-stream (mp3, wav, m4a, ogg, flac, webm).
modelstringpar défaut —Accepted and ignored: there is one engine. Send whisper-1.
languageISO 639-1, e.g. bgpar défaut autoOptional. Omit it and the language is detected.
response_formatjson | text | verbose_json | srt | vttpar défaut jsonAn unknown value falls back to json.
timestamp_granularities[]segment | wordpar défaut segmentverbose_json only. word adds a words array (see below).
promptstringpar défaut —Accepted and ignored.
temperaturefloatpar défaut 0Accepted and ignored.

verbose_json

Segment début/fin proviennent du moteur. Les minutages des mots (timestamp_granularities[]=word) sont estimés: la durée de chaque segment est répartie entre ses mots selon leur nombre de caractères. Ils ne sont pas alignés par forçage. Chaque segment porte un mots clé, vide sauf si vous avez demandé des mots.

json
{
  "task": "transcribe",
  "language": "bg",          // echo of the request; "auto" when omitted
  "duration": 12.3,
  "text": "Full transcript…",
  "segments": [
    { "id": 0, "start": 0.0, "end": 3.2, "text": "…", "words": [] }
  ]
}

Non pris en charge

  • POST /v1/audio/translations renvoie 405.
  • Transcription en streaming et API Realtime.

Erreurs

CodeCorps
400{"detail": "audio_too_short"} · "no_speech_detected" · "clip_too_long: max 600s per request"
401{"detail": "authentication_required"}: missing or invalid key
402{"detail": {"error": "insufficient_credits", …}}: full body below
403{"detail": "email_not_verified"}: verify the account's email address
405{"detail": "Method Not Allowed"}: /v1/audio/translations
413{"detail": "audio_too_large"}: file over 25 MB
415{"detail": "unsupported_media_type"}: file part is not audio
json
// 402 — the balance cannot cover this file
{
  "detail": {
    "error": "insufficient_credits",
    "plan_tier": "free",
    "monthly_grant": 250,
    "monthly_used": 250,
    "pack_credits": 0,
    "requested": 41,
    "upgrade_url": "/pricing",
    "offer": {
      "reason": "insufficient_credits",
      "headline": "You are out of credits",
      "detail": "This request needs 41 credits. …",
      "plan": { "tier": "pro", "price_eur": 29, "credits_per_month": 1200000 },
      "actions": [
        { "kind": "upgrade", "label": "Upgrade to Pro — €29/mo", "url": "https://audexum.com/r/402" },
        { "kind": "pack", "label": "Buy 250,000 credits — €7", "url": "https://audexum.com/pricing#packs" }
      ]
    }
  }
}

POST/api/batch

Envoyez jusqu’à 50 textes en une seule requête. Attendez la fin du traitement, puis téléchargez un zip.

curl
# submit
curl -X POST https://audexum.com/api/batch \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"texts": ["one", "two"], "voice": "F2", "lang": "en"}'

# poll
curl -H "Authorization: Bearer sk_live_..." \
  https://audexum.com/api/batch/$JOB_ID

# download once status=done
curl -H "Authorization: Bearer sk_live_..." \
  https://audexum.com/api/batch/$JOB_ID/download -O

Webhooks

Configurez un point de terminaison webhook dans votre les paramètres développeur pour recevoir des notifications POST signées. Nous envoyons du JSON avec un X-Audexum-Signature en-tête. Vérifiez-le avant de traiter la requête.

Structure de la charge utile

json
{
  "event": "quota.warning_80",
  "data": {
    "monthly_grant": 3000,
    "monthly_used": 24000,
    "monthly_remaining": 6000,
    "overage_enabled": false,
    "plan_tier": "free",
    "period_end": "2026-06-30"
  },
  "timestamp": "2026-06-12T14:22:00.000000+00:00"
}

Événements

ChampSaisissezPar défautRemarques
quota.warning_80stringpar défaut —Fired when monthly quota crosses 80% used.
quota.exhaustedstringpar défaut —Fired when monthly quota is fully consumed.
batch.completedstringpar défaut —Fired when a batch job finishes.
audiobook.completedstringpar défaut —Fired when an audiobook job finishes.

Vérification de la signature

Chaque envoi comprend X-Audexum-Signature: sha256=<hex>, calculé via HMAC-SHA256 sur le corps brut de la requête à l’aide de votre secret de webhook.

python
import hashlib, hmac

def verify_signature(body: bytes, secret: str, sig_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig_header)

# In your FastAPI/Flask/Django handler:
# body = await request.body()
# sig  = request.headers["X-Audexum-Signature"]
# if not verify_signature(body, WEBHOOK_SECRET, sig):
#     return 401
curl
# Configure endpoint (session auth — browser only)
curl -X PUT https://audexum.com/api/account/webhook \
  -H "Cookie: audexum_session=..." \
  -H "X-Requested-With: XMLHttpRequest" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhooks/audexum"}'
# Response contains secret — store it, shown once only.

# Remove endpoint
curl -X DELETE https://audexum.com/api/account/webhook \
  -H "Cookie: audexum_session=..." \
  -H "X-Requested-With: XMLHttpRequest"
Points de terminaison HTTPS uniquement. HTTP est refusé.
Les IP privées et de loopback sont bloquées (protection SSRF).
Délai de 5 s, 2 nouvelles tentatives avec intervalle exponentiel (1 s, 2 s).
L’envoi est effectué sans attendre de confirmation : il ne bloque jamais une requête de synthèse.

Erreurs

CodeSignification
400Requête incorrecte : voix/langue non valide, texte vide ou streaming avec un format non-WAV
401Clé API manquante ou non valide
402insufficient_credits : quota mensuel dépassé ; consultez /api/usage et /pricing pour les options de mise à niveau
402feature_gated : la fonctionnalité nécessite un forfait supérieur (voir error.feature et error.min_tier)
422URL de webhook non valide (non HTTPS, IP privée ou impossible à résoudre)
429Trop de requêtes : réduisez votre fréquence de requête et réessayez
503Serveur occupé (limite de concurrence atteinte) : réessayez avec un délai d’attente exponentiel et respectez l’en-tête Retry-After

Limites de débit et usage équitable

  • Limite de concurrence partagée : les requêtes au-delà de cette limite reçoivent 503 + Retry-After
  • Des fréquences de requêtes abusives prolongées peuvent être limitées (usage raisonnable)
  • Quota mensuel de crédits selon le niveau de votre forfait
  • Contactez-nous pour obtenir une capacité dédiée ou le paiement à l’usage

Besoin d’aide ? Écrivez à [email protected].

Votre premier appel est à une requête curl de distance.