Saltar al contenido
API Reference · v1

Build with Audexum.

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

Autenticación

Genera una clave de API desde ajustes de desarrollador. Envíala como un token Bearer en cada solicitud.

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

POST/api/synthesize

Genera audio a partir de texto. Devuelve audio/wav de forma predeterminada (44.1 kHz, PCM de 16 bits, mono). Usa format para MP3/OGG/Opus o stream=true para streaming por bloques con baja latencia.

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

Cuerpo de la solicitud

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

Niveles de voz

Elige un nivel con backend. Cada nivel tiene sus propias voces y un multiplicador de créditos por carácter. Si envías una voz desconocida para un nivel, recibirás un 400.

Omite backend y el nivel se inferirá: una voz V2 (F1..F5, M1..M5) te mantiene en V2 Multilingual, una voz de V3 selecciona V3 Expressive y no indicar ninguno te da V3 Expressive enAtlas. Las integraciones existentes que solo envían unavoz no se ven afectadas y mantienen la facturación según el multiplicador de su nivel.

backendnivelcostevoces
v1V1 Instant: rápido, pensado para inglés1×Consulta /api/voices
v2V2 Multilingual: 32 idiomas, incluido el búlgaro1.5×F1..F5, M1..M5
v3V3 Expressive: la voz más expresiva, con emoción y estilo2×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

Encabezados de respuesta

CampoEscribePredeterminadoNotas
Content-Typestringpredeterminado —audio/wav · audio/mpeg · audio/ogg · audio/opus
X-Gen-Time-Msintpredeterminado —Wall-clock generation time, ms.
X-Audio-Duration-Sfloatpredeterminado —Output audio duration, seconds.
X-RTFfloatpredeterminado —Audio / generation ratio. >1 = faster than real-time.
X-Formatstringpredeterminado —Echo of requested format.
X-Stream1predeterminado —Present when stream=true; body is concatenated WAV chunks.

Formatos de salida (OGG / Opus / MP3)

Añade "format": "ogg" (o mp3 / opus) para obtener una respuesta transcodificada. La cuota es la misma independientemente del formato. La marca de agua AudioSeal se conserva tras la codificación 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-TypeCódec
wavaudio/wavPCM 16-bit, 44.1 kHz (sin transcodificar)
mp3audio/mpeglibmp3lame VBR ~192 kbps
oggaudio/ogglibopus 96 kbps, 48 kHz
opusaudio/opuslibopus 96 kbps, 48 kHz (contenedor Ogg)

TTS en streaming

Añade "stream": true para recibir el audio a medida que se genera. La respuesta es un flujo de transferencia por fragmentos que concatena archivos WAV. Cada fragmento es un WAV completo y válido (cabecera RIFF de 44 bytes + PCM), por lo que puedes comenzar la reproducción inmediatamente. La cuota se reserva para todo el texto desde el principio, igual que en una llamada sin transmisión en streaming. La transmisión en streaming requiere format=wav (el valor predeterminado).

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.
Notas sobre el streaming: el texto se divide por límites de oración (~1–3 oraciones por bloque). El formato debe ser wav. La latencia del primer bloque se registra en el servidor. El encabezado de respuesta X-Stream: 1 confirma el modo de streaming.

POST/api/transcribe

Transcribe voz a texto. Envía el audio como multipart/form-data. Requiere una clave sin restricciones (las claves de widget están limitadas a /api/synthesize). Se cobra a 200 créditos por minuto de audio.

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

Campos del formulario

CampoNotas
audioobligatorio. Un archivo audio/* de hasta 25 MB y 600 segundos.
timestampsBooleano opcional. Incluye los tiempos de inicio y fin de cada segmento.
vocabularyOpcional. Hasta 2000 caracteres de términos del dominio para orientar el reconocimiento.
clean / modeOpcional. Postprocesa la transcripción (clean, email, professional, bullets, concise).

Respuesta

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

Voz a texto compatible con OpenAI. Una herramienta que permita cambiar la URL base de OpenAI puede usar Audexum configurándola como https://audexum.com/v1, sin cambiar el código. Utiliza el mismo motor y la misma facturación que /api/transcribe: 200 créditos por minuto de audio. Envía multipart/form-data.

La autenticación es Authorization: Bearer sk_live_…. Crea la clave en ajustes de desarrollador (es necesario iniciar sesión). Usa una clave sk_live_ clave; las claves de widget restringidas reciben 403 aquí.

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)

Campos del formulario

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

verbose_json

Segmento inicio/fin proceden del motor. Los tiempos de las palabras (timestamp_granularities[]=word) son estimados: el intervalo de cada segmento se reparte entre sus palabras según la longitud en caracteres. No se alinean de forma forzada. Cada segmento lleva un palabras clave, vacía a menos que solicites palabras.

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

No compatible

  • POST /v1/audio/translations devuelve 405.
  • Transcripción en streaming y API en tiempo real.

Errores

CódigoCuerpo
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

Envía hasta 50 textos en una sola solicitud. Consulta cuándo terminen y descarga 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

Configura un endpoint de webhook en tu ajustes de desarrollador para recibir notificaciones POST firmadas. Enviamos JSON con un X-Audexum-Signature cabecera. Verifícala antes de procesarla.

Estructura de los datos

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

Eventos

CampoEscribePredeterminadoNotas
quota.warning_80stringpredeterminado —Fired when monthly quota crosses 80% used.
quota.exhaustedstringpredeterminado —Fired when monthly quota is fully consumed.
batch.completedstringpredeterminado —Fired when a batch job finishes.
audiobook.completedstringpredeterminado —Fired when an audiobook job finishes.

Verificación de firmas

Cada entrega incluye X-Audexum-Signature: sha256=<hex>, calculada como HMAC-SHA256 sobre el cuerpo原始 de la solicitud mediante el secreto de tu 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"
El envío es «dispara y olvida»: nunca bloquea una petición de síntesis.
IP privadas/de loopback bloqueadas (protección SSRF).
Tiempo de espera de 5 s, 2 reintentos con espera exponencial (1 s, 2 s).
Petición incorrecta: voz o idioma no válidos, texto vacío o stream junto con un formato distinto de WAV

Errores

CódigoSignificado
400insufficient_credits: Cuota mensual superada; consulta /api/usage y /pricing para conocer las opciones de mejora
401Falta la clave de API o no es válida
402feature_gated: La función requiere un plan superior (consulta error.feature y error.min_tier)
402Demasiadas peticiones: reduce la frecuencia y vuelve a intentarlo
422URL de webhook no válida (no es HTTPS, es una IP privada o no se puede resolver)
429Servidor ocupado (límite de concurrencia alcanzado): reinténtalo con espera exponencial y respeta Retry-After
503Servidor ocupado (se ha alcanzado el límite de concurrencia): inténtalo de nuevo con espera exponencial y respeta Retry-After

Límites de tasa y uso justo

  • Límite compartido de concurrencia: las solicitudes que lo superen reciben 503 + Retry-After
  • Las frecuencias de solicitudes abusivas sostenidas pueden limitarse (uso justo)
  • Cuota mensual de créditos según el nivel de tu plan
  • Contáctanos si necesitas capacidad dedicada o PAYG

¿Atascado? Escribe a [email protected].

Conecta un asistente de IA