Перейти к содержимому
API Reference · v1

Build with Audexum.

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

Аутентификация

Создайте ключ API в настройках разработчика. Отправляйте его как Bearer-токен в каждом запросе.

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

POST/api/synthesize

Генерируйте аудио из текста. По умолчанию возвращает audio/wav (44.1 kHz, 16-bit PCM, моно). Используйте format для MP3/OGG/Opus или stream=true для потоковой передачи с низкой задержкой частями.

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

Тело запроса

ПолеВведитеПо умолчаниюПримечания
textstringпо умолчанию requiredUp to ~5,000 characters per call.
voiceper tier (see Voice tiers)по умолчанию AtlasVoice ids are tier-specific. The default follows backend.
langen, bg, ko, ja, ar, de, …по умолчанию en33 supported. See /api/voices.
speed0.5–2.0по умолчанию 1.05 (V1 and V3: 1.0)Speaking pace, on every engine except V4. Pitch is kept.
steps4–16по умолчанию 8Diffusion steps. More = higher quality, slower.
formatwav | mp3 | ogg | opusпо умолчанию wavOutput format. Quota is identical across formats.
streambooleanпо умолчанию falseStream chunked WAV. Only format=wav, and V1/V2 only. V3 Expressive returns the whole file and ignores stream.
backendv3 | v2 | v1по умолчанию v3Voice tier. Omit it and you get V3 Expressive. See Voice tiers below.
instructstringпо умолчанию ""V3 only. Natural-language style/emotion, e.g. "warm and slow". Ignored by V1/V2.

Уровни голосов

Выберите уровень с помощью backend. У каждого уровня есть собственные голоса и множитель расхода кредитов за символ. При передаче неизвестного голоса для уровня возвращается 400.

Если не указать backend уровень определяется автоматически: голос V2 (F1..F5, M1..M5) оставляет вас на V2 Multilingual, голос V3 выбирает V3 Expressive, а если не указать ни один, вы получаете V3 Expressive наAtlas. Существующие интеграции, которые отправляют толькоголос , работают без изменений, а расход кредитов определяется множителем соответствующего уровня.

backendуровнястоимостиголосов
v1V1 Instant: быстрый, прежде всего для английского языка1×См. /api/voices
v2V2 Multilingual: 32 языка, включая болгарский1.5×F1..F5, M1..M5
v3V3 Expressive: максимальная выразительность, эмоции и стиль2×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

Заголовки ответа

ПолеВведитеПо умолчаниюПримечания
Content-Typestringпо умолчанию —audio/wav · audio/mpeg · audio/ogg · audio/opus
X-Gen-Time-Msintпо умолчанию —Wall-clock generation time, ms.
X-Audio-Duration-Sfloatпо умолчанию —Output audio duration, seconds.
X-RTFfloatпо умолчанию —Audio / generation ratio. >1 = faster than real-time.
X-Formatstringпо умолчанию —Echo of requested format.
X-Stream1по умолчанию —Present when stream=true; body is concatenated WAV chunks.

Форматы вывода (OGG / Opus / MP3)

Добавьте "format": "ogg" (или mp3 / opus), чтобы получить перекодированный ответ. Квота одинакова для всех форматов. Водяной знак AudioSeal сохраняется после кодирования в 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-TypeКодек
wavaudio/wavPCM 16-bit, 44,1 kHz (без перекодирования)
mp3audio/mpeglibmp3lame VBR ~192 kbps
oggaudio/ogglibopus 96 kbps, 48 kHz
opusaudio/opuslibopus 96 kbps, 48 kHz (контейнер Ogg)

Потоковый TTS

Добавьте "stream": true для получения аудио по мере его создания. Ответ представляет собой поток с передачей фрагментами, состоящий из объединённых WAV-файлов. Каждый фрагмент — полноценный корректный WAV-файл (44-байтный заголовок RIFF + PCM), поэтому воспроизведение можно начать сразу. Квота резервируется целиком для всего текста заранее, как и при запросе без потоковой передачи. Для потоковой передачи требуется format=wav (по умолчанию).

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.
Примечания к потоковой передаче: текст разбивается по границам предложений (~1–3 предложения в каждом фрагменте). Формат должен быть wav. Задержка первого фрагмента фиксируется на сервере. Заголовок ответа X-Stream: 1 подтверждает режим потоковой передачи.

POST/api/transcribe

Транскрибируйте речь в текст. Отправляйте аудио как multipart/form-data. Требуется неограниченный ключ (ключи виджета ограничены значением /api/synthesize). Стоимость — 200 кредитов за минуту аудио.

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

Поля формы

ПолеПримечания
audioОбязательный. Аудиофайл audio/* размером до 25 MB и длительностью до 600 секунд.
timestampsНеобязательное логическое значение. Включать время начала и окончания каждого сегмента.
vocabularyНеобязательно. До 2000 символов отраслевых терминов для повышения точности распознавания.
clean / modeНеобязательно. Постобработка транскрипта (clean, email, professional, bullets, concise).

Ответ

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 API преобразователь речи в текст. Инструмент, позволяющий изменить базовый URL OpenAI, может использовать Audexum, указав https://audexum.com/v1, без изменения кода. Используется тот же движок и тарификация, что и /api/transcribe: 200 кредитов за минуту аудио. Отправьте multipart/form-data.

Auth: Authorization: Bearer sk_live_…Создайте ключ в настройках разработчика (необходимо войти). Используйте секретный sk_live_ ключ; ключи виджета с ограничениями получат здесь ошибку 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)

Поля формы

ПолеВведитеПо умолчаниюПримечания
filefileпо умолчанию requiredUp to 25 MB and 600 seconds. Content-Type audio/*, video/webm, video/ogg or application/octet-stream (mp3, wav, m4a, ogg, flac, webm).
modelstringпо умолчанию —Accepted and ignored: there is one engine. Send whisper-1.
languageISO 639-1, e.g. bgпо умолчанию autoOptional. Omit it and the language is detected.
response_formatjson | text | verbose_json | srt | vttпо умолчанию jsonAn unknown value falls back to json.
timestamp_granularities[]segment | wordпо умолчанию segmentverbose_json only. word adds a words array (see below).
promptstringпо умолчанию —Accepted and ignored.
temperaturefloatпо умолчанию 0Accepted and ignored.

verbose_json

Сегмент start/end поступают от движка. Временны́е метки слов (timestamp_granularities[]=word) являются оценочными: длительность каждого сегмента распределяется по словам пропорционально количеству символов. Они не получены методом принудительного выравнивания. Каждый сегмент содержит words ключ, пустой, если вы не запрашивали слова.

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

Не поддерживается

  • POST /v1/audio/translations возвращает 405.
  • Потоковая транскрибация и Realtime API.

Ошибки

КодТело
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

Отправляйте до 50 текстов в одном запросе. Опрашивайте статус выполнения, затем скачивайте 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

Вебхуки

Настройте конечную точку вебхука в вашем настройках разработчика для получения подписанных POST-уведомлений. Мы отправляем JSON с заголовком X-Audexum-Signature заголовок. Проверьте его перед обработкой.

Структура 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"
}

События

ПолеВведитеПо умолчаниюПримечания
quota.warning_80stringпо умолчанию —Fired when monthly quota crosses 80% used.
quota.exhaustedstringпо умолчанию —Fired when monthly quota is fully consumed.
batch.completedstringпо умолчанию —Fired when a batch job finishes.
audiobook.completedstringпо умолчанию —Fired when an audiobook job finishes.

Проверка подписи

Каждая отправка включает X-Audexum-Signature: sha256=<hex>, вычисляется как HMAC-SHA256 по необработанному телу запроса с использованием вашего секрета вебхука.

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"
Только HTTPS-эндпоинты. HTTP отклоняется.
Частные и локальные IP-адреса заблокированы (защита от SSRF).
Тайм-аут 5 с, 2 повторные попытки с экспоненциальной задержкой (1 с, 2 с).
Доставка происходит без ожидания ответа: она никогда не блокирует запрос синтеза.

Ошибки

КодЗначение
400Некорректный запрос: недопустимый голос или язык, пустой текст либо потоковая передача с форматом, отличным от WAV
401Отсутствует или недействительный ключ API
402insufficient_credits: превышена месячная квота; варианты обновления см. в /api/usage и /pricing
402feature_gated: для функции требуется тариф выше (см. error.feature и error.min_tier)
422Недопустимый URL вебхука (не HTTPS, частный IP-адрес или не удаётся разрешить)
429Слишком много запросов: снизьте частоту запросов и повторите попытку
503Сервер занят (достигнут лимит параллельных запросов): повторите с экспоненциальной задержкой и соблюдайте Retry-After

Лимиты запросов и добросовестное использование

  • Общий лимит параллельных запросов: запросы сверх него получают 503 + Retry-After
  • Устойчиво высокая частота злоупотребляющих запросов может ограничиваться (fair use)
  • Месячная квота кредитов в зависимости от уровня вашего плана
  • Свяжитесь с нами для получения выделенной мощности или PAYG

Что-то не работает? Напишите на [email protected].

Ваш первый вызов — в одном curl от вас.