Vai al contenuto
API Reference · v1

Build with Audexum.

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

Autenticazione

Genera una chiave API da Impostazioni sviluppatore. Invia come token Bearer con ogni richiesta.

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

POST/api/synthesize

Genera audio da testo. Restituisce audio/wav per impostazione predefinita (44.1 kHz, PCM 16-bit, mono). Usa format per MP3/OGG/Opus oppure stream=true per lo streaming a blocchi a bassa latenza.

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

Corpo della richiesta

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

Livelli vocali

Scegli un livello con backend. Ogni livello ha voci proprie e un moltiplicatore di crediti per carattere. L’invio di una voce sconosciuta per il livello restituisce 400.

Ometti backend e il livello viene dedotto: una voce V2 (F1..F5, M1..M5) ti mantiene su V2 Multilingual, una voce V3 seleziona V3 Expressive e, se non ne scegli nessuna, ti dà V3 Expressive suAtlas. Le integrazioni esistenti che inviano solo unavoce non sono interessate e mantengono la fatturazione al moltiplicatore del rispettivo livello.

backendtiercostovoci
v1V1 Instant: rapida, incentrata sull’inglese1×Consulta /api/voices
v2V2 Multilingual: 32 lingue, incluse il bulgaro1.5×F1..F5, M1..M5
v3V3 Expressive: la più espressiva, emozione e stile2×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

Intestazioni della risposta

CampoDigitaPredefinitoNote
Content-Typestringpredefinito —audio/wav · audio/mpeg · audio/ogg · audio/opus
X-Gen-Time-Msintpredefinito —Wall-clock generation time, ms.
X-Audio-Duration-Sfloatpredefinito —Output audio duration, seconds.
X-RTFfloatpredefinito —Audio / generation ratio. >1 = faster than real-time.
X-Formatstringpredefinito —Echo of requested format.
X-Stream1predefinito —Present when stream=true; body is concatenated WAV chunks.

Formati di output (OGG / Opus / MP3)

Aggiungi "format": "ogg" (oppure mp3 / opus) per ottenere una risposta transcodificata. La quota è identica indipendentemente dal formato. Il watermark AudioSeal sopravvive alla codifica 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 (nessuna transcodifica)
mp3audio/mpeglibmp3lame VBR ~192 kbps
oggaudio/ogglibopus 96 kbps, 48 kHz
opusaudio/opuslibopus 96 kbps, 48 kHz (contenitore Ogg)

Sintesi vocale in streaming

Aggiungi "stream": true per ricevere l’audio mentre viene generato. La risposta è uno stream chunked-transfer di file WAV concatenati. Ogni chunk è un WAV completo e valido (header RIFF da 44 byte + PCM), quindi puoi iniziare subito la riproduzione. La quota viene riservata per l’intero testo fin dall’inizio, esattamente come in una chiamata senza streaming. Lo streaming richiede format=wav (il valore predefinito).

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.
Note sullo streaming: il testo viene diviso in base ai limiti delle frasi (~1–3 frasi per chunk). Il formato deve essere wav. La latenza del primo chunk viene registrata lato server. L’intestazione della risposta X-Stream: 1 conferma la modalità streaming.

POST/api/transcribe

Trascrivi il parlato in testo. Invia l’audio come multipart/form-data. Richiede una chiave senza restrizioni (le chiavi dei widget sono limitate a /api/synthesize). Fatturazione a 200 crediti al minuto di audio.

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

Campi del modulo

CampoNote
audioObbligatorio. Un file audio/*, fino a 25 MB e 600 secondi.
timestampsBooleano facoltativo. Includi gli orari di inizio e fine per ogni segmento.
vocabularyFacoltativo. Fino a 2000 caratteri di termini specifici del settore per orientare il riconoscimento.
clean / modeFacoltativo. Elabora ulteriormente la trascrizione (pulizia, email, professionale, elenchi puntati, conciso).

Risposta

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

Speech-to-text compatibile con OpenAI. Uno strumento che ti permette di modificare l’URL base di OpenAI può usare Audexum impostandolo su https://audexum.com/v1, senza modifiche al codice. Usa lo stesso motore e la stessa fatturazione di /api/transcribe: 200 crediti al minuto di audio. Invia multipart/form-data.

L’autenticazione è Authorization: Bearer sk_live_…. Crea la chiave in Impostazioni sviluppatore (è necessario accedere). Usa una chiave segreta sk_live_ chiave; le chiavi dei widget limitate ricevono qui un 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)

Campi del modulo

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

verbose_json

Segmento start/end provengono dal motore. I tempi delle parole (timestamp_granularities[]=word) sono stimati: l’intervallo di ogni segmento viene suddiviso tra le parole in base alla lunghezza in caratteri. Non vengono sottoposti ad allineamento forzato. Ogni segmento riporta un parole chiave, vuota a meno che tu non abbia richiesto le parole.

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 supportato

  • POST /v1/audio/translations restituisce 405.
  • Trascrizione in streaming e API Realtime.

Errori

CodiceCorpo
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

Invia fino a 50 testi in una richiesta. Attendi il completamento, poi scarica uno 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

Webhook

Configura un endpoint webhook nel tuo Impostazioni sviluppatore per ricevere notifiche POST firmate. Inviamo JSON con un X-Audexum-Signature header. Verificalo prima di elaborarlo.

Struttura del payload

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

Eventi

CampoDigitaPredefinitoNote
quota.warning_80stringpredefinito —Fired when monthly quota crosses 80% used.
quota.exhaustedstringpredefinito —Fired when monthly quota is fully consumed.
batch.completedstringpredefinito —Fired when a batch job finishes.
audiobook.completedstringpredefinito —Fired when an audiobook job finishes.

Verifica della firma

Ogni invio include X-Audexum-Signature: sha256=<hex>, calcolato come HMAC-SHA256 sul corpo della richiesta non elaborato usando la secret del tuo 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"
Solo endpoint HTTPS. HTTP viene rifiutato.
IP privati/loopback bloccati (protezione SSRF).
Timeout di 5 s, 2 tentativi con backoff esponenziale (1 s, 2 s).
L’invio è fire-and-forget: non blocca mai una richiesta di sintesi.

Errori

CodiceSignificato
400Richiesta non valida: voice/lang non valide, testo vuoto oppure stream con formato non wav
401Chiave API mancante o non valida
402insufficient_credits: quota mensile superata; consulta /api/usage e /pricing per le opzioni di upgrade
402feature_gated: la funzionalità richiede un piano superiore (vedi error.feature e error.min_tier)
422URL webhook non valido (non HTTPS, IP privato o non risolvibile)
429Troppe richieste: riduci la frequenza delle richieste e riprova
503Server occupato (limite di concorrenza raggiunto): riprova con backoff esponenziale; rispetta Retry-After

Limiti di frequenza e uso corretto

  • Limite di concorrenza condiviso: le richieste che lo superano ricevono 503 + Retry-After
  • Frequenze di richieste abusive persistenti possono essere limitate (uso corretto)
  • Quota mensile di crediti prevista dal tuo piano
  • Contattaci per capacità dedicate o PAYG

Bloccato? Scrivi a [email protected].

La tua prima chiamata è a una curl di distanza.