Zum Inhalt springen
API Reference · v1

Build with Audexum.

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

Authentifizierung

Generiere einen API-Schlüssel in den Entwicklereinstellungen. Sende ihn bei jeder Anfrage als Bearer-Token.

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

POST/api/synthesize

Erzeuge Audio aus Text. Gibt standardmäßig audio/wav zurück (44.1 kHz, 16-Bit-PCM, Mono). Verwende format für MP3/OGG/Opus oder stream=true für latenzarmes Streaming in Blöcken.

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

Anfragetext

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

Stimmstufen

Wähle eine Stufe mit backend. Jede Stufe hat eigene Stimmen und einen Credit-Multiplikator pro Zeichen. Wird für eine Stufe eine unbekannte Stimme gesendet, wird 400 zurückgegeben.

Lass backend weg, damit die Stufe automatisch erkannt wird: Eine V2-Stimme (F1..F5, M1..M5) hält dich bei V2 Multilingual, eine V3-Stimme wählt V3 Expressive, und ohne Benennung erhältst du V3 Expressive aufAtlas. Bestehende Integrationen, die nur eineStimme senden, bleiben unverändert und werden weiterhin mit dem Multiplikator ihrer Stufe abgerechnet.

backendStufeKostenStimmen
v1V1 Instant: schnell, zuerst für Englisch1×/api/voices ansehen
v2V2 Multilingual: 32 Sprachen, einschließlich Bulgarisch1.5×F1..F5, M1..M5
v3V3 Expressive: ausdrucksstärkste Variante, Emotion & Stil2×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

Antwort-Header

FeldGibStandardHinweise
Content-TypestringStandard —audio/wav · audio/mpeg · audio/ogg · audio/opus
X-Gen-Time-MsintStandard —Wall-clock generation time, ms.
X-Audio-Duration-SfloatStandard —Output audio duration, seconds.
X-RTFfloatStandard —Audio / generation ratio. >1 = faster than real-time.
X-FormatstringStandard —Echo of requested format.
X-Stream1Standard —Present when stream=true; body is concatenated WAV chunks.

Ausgabeformate (OGG / Opus / MP3)

Füge "format": "ogg" (oder mp3 / opus) hinzu, um eine transcodierte Antwort zu erhalten. Das Kontingent ist unabhängig vom Format identisch. Das AudioSeal-Wasserzeichen bleibt beim MP3-Encoding erhalten.

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 (kein Transcoding)
mp3audio/mpeglibmp3lame VBR ~192 kbps
oggaudio/ogglibopus 96 kbps, 48 kHz
opusaudio/opuslibopus 96 kbps, 48 kHz (Ogg-Container)

Streaming-TTS

Füge "stream": true , um Audio während der Generierung zu erhalten. Die Antwort ist ein Chunked-Transfer-Stream aus zusammengeführten WAV-Dateien. Jeder Chunk ist eine vollständige, gültige WAV-Datei (44-Byte-RIFF-Header + PCM), sodass du sofort mit der Wiedergabe beginnen kannst. Das Kontingent wird vorab für den gesamten Text reserviert, genau wie bei einem Aufruf ohne Streaming. Streaming erfordert format=wav (das Standardformat).

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.
Hinweise zum Streaming: Der Text wird an Satzgrenzen geteilt (~1–3 Sätze pro Block). Das Format muss wavsein. Die Latenz bis zum ersten Block wird serverseitig protokolliert. Der Antwort-Header X-Stream: 1 bestätigt den Streaming-Modus.

POST/api/transcribe

Transkribiere Sprache in Text. Sende Audio als multipart/form-data. Erfordert einen unbeschränkten Schlüssel (Widget-Schlüssel sind auf /api/synthesizebeschränkt). Kosten: 200 Credits pro Minute Audio.

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

Formularfelder

FeldHinweise
audioErforderlich. Eine audio/*-Datei mit bis zu 25 MB und 600 Sekunden.
timestampsOptionaler boolescher Wert. Start- und Endzeiten pro Segment einbeziehen.
vocabularyOptional. Bis zu 2000 Zeichen Fachbegriffe, um die Erkennung zu beeinflussen.
clean / modeOptional. Das Transkript nachbearbeiten (clean, email, professional, bullets, concise).

Antwort

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

OpenAI-kompatible Speech-to-Text-Funktion. Ein Tool, mit dem sich die OpenAI-Basis-URL ändern lässt, kann Audexum verwenden, indem diese auf https://audexum.com/v1, ohne Codeänderung. Es verwendet dieselbe Engine und Abrechnung wie /api/transcribe: 200 Credits pro Minute Audio. Sende multipart/form-data.

Die Authentifizierung erfolgt über Authorization: Bearer sk_live_…. Erstelle den Schlüssel in Entwicklereinstellungen (Anmeldung erforderlich). Verwende einen geheimen sk_live_ Schlüssel; eingeschränkte Widget-Schlüssel erhalten hier 403.

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)

Formularfelder

FeldGibStandardHinweise
filefileStandard requiredUp to 25 MB and 600 seconds. Content-Type audio/*, video/webm, video/ogg or application/octet-stream (mp3, wav, m4a, ogg, flac, webm).
modelstringStandard —Accepted and ignored: there is one engine. Send whisper-1.
languageISO 639-1, e.g. bgStandard autoOptional. Omit it and the language is detected.
response_formatjson | text | verbose_json | srt | vttStandard jsonAn unknown value falls back to json.
timestamp_granularities[]segment | wordStandard segmentverbose_json only. word adds a words array (see below).
promptstringStandard —Accepted and ignored.
temperaturefloatStandard 0Accepted and ignored.

verbose_json

Segment start/end stammen von der Engine. Wortzeitangaben (timestamp_granularities[]=word) sind geschätzt: Die Zeitspanne jedes Segments wird anhand der Zeichenzahl auf seine Wörter verteilt. Sie werden nicht per Forced Alignment bestimmt. Jedes Segment enthält einen Wörter Schlüssel, leer, sofern du keine Wörter angefordert hast.

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": [] }
  ]
}

Nicht unterstützt

  • POST /v1/audio/translations liefert 405.
  • Streaming-Transkription und Realtime-API.

Fehler

CodeBody
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

Sende bis zu 50 Texte in einer Anfrage. Warte auf den Abschluss und lade dann eine ZIP-Datei herunter.

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

Konfiguriere einen Webhook-Endpunkt in deiner Entwicklereinstellungen um signierte POST-Benachrichtigungen zu erhalten. Wir senden JSON mit einem X-Audexum-Signature Header. Überprüfe ihn vor der Verarbeitung.

Payload-Struktur

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

Events

FeldGibStandardHinweise
quota.warning_80stringStandard —Fired when monthly quota crosses 80% used.
quota.exhaustedstringStandard —Fired when monthly quota is fully consumed.
batch.completedstringStandard —Fired when a batch job finishes.
audiobook.completedstringStandard —Fired when an audiobook job finishes.

Signaturprüfung

Jede Übermittlung enthält X-Audexum-Signature: sha256=<hex>, berechnet als HMAC-SHA256 über den unveränderten Request-Body mit deinem Webhook-Secret.

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"
Nur HTTPS-Endpunkte. HTTP wird abgelehnt.
Private/Loopback-IPs werden blockiert (SSRF-Schutz).
5 s Zeitlimit, 2 Wiederholungen mit exponentiellem Backoff (1 s, 2 s).
Die Zustellung erfolgt im Fire-and-forget-Verfahren und blockiert niemals eine Syntheseanfrage.

Fehler

CodeBedeutung
400Ungültige Anfrage: ungültige Stimme/Sprache, leerer Text oder Streaming + Nicht-WAV-Format
401Fehlender oder ungültiger API-Schlüssel
402insufficient_credits: Monatliches Kontingent überschritten; Upgrade-Optionen unter /api/usage und /pricing
402feature_gated: Für die Funktion ist ein höherer Plan erforderlich (siehe error.feature und error.min_tier)
422Ungültige Webhook-URL (nicht HTTPS, private IP-Adresse oder nicht auflösbar)
429Zu viele Anfragen: Reduziere deine Anfragefrequenz und versuche es erneut
503Server ausgelastet (Limit für parallele Anfragen erreicht): Mit exponentiellem Backoff erneut versuchen; Retry-After beachten

Nutzungsgrenzen & faire Nutzung

  • Gemeinsames Limit für parallele Anfragen: Anfragen darüber erhalten 503 + Retry-After
  • Anhaltend missbräuchliche Anfrageraten können gedrosselt werden (faire Nutzung)
  • Monatliches Guthabenkontingent deines Tarifs
  • Kontaktiere uns für dedizierte Kapazität oder PAYG

Du hängst fest? Schreib eine E-Mail an [email protected].

Dein erster Aufruf ist nur einen curl-Befehl entfernt.