Справочник
API v1 — эндпоинты
GET/api/v1/voicesКаталог голосов: id, язык, пол, стиль, лицензия, пример
GET/api/v1/voices/mineВаши голоса: приватные клоны (созданные вами) + купленные на маркетплейсе. Требует ключ. Приватные голоса других аккаунтов сюда НЕ попадают и в общий каталог не светятся
POST/api/v1/ttsСинтез речи → WAV или MP3 (параметр format)
POST/api/v1/tts_streamПотоковый синтез (chunked PCM) для low-latency — чистый поток без пост-эффектов и без mp3
POST/api/v1/voices/cloneСоздать голос: name (≤80), audio_b64 (≤10 МБ base64), ref_text (=аудио слово-в-слово, ≤2000), consent="voice-data-consent,privacy", language? → voice id
POST/api/v1/transcribeРасшифровка короткого фрагмента: audio_b64, language? (полное имя) → текст. Длительность учитывается в месячном лимите минут расшифровки тарифа
GET/api/v1/statusГотовность движка (real-time агенты): ready, model_ready, latency_ms
POST/api/v1/warmupПрогрев движка перед сессией звонков (без списания символов)
GET /api/v1/voices — фильтры: q (поиск по названию/стилю/описанию), language (ru, en, de…), gender (male/female), limit (по умолч. 200, макс. 500), offset. Поле voice из ответа передавайте в POST /tts.
Свои голоса (приватные). Клон, который вы создали (в кабинете или через POST /voices/clone), привязан к вашему аккаунту и в общий каталог GET /voices НЕ попадает — другие клиенты его не видят. Чтобы получить список своих голосов программно (и их voice-id для синтеза), вызывайте GET /api/v1/voices/mine со своим ключом — он вернёт только ВАШИ клоны и купленные голоса. Синтез своим голосом: передайте его voice в POST /tts с тем же ключом — озвучить его сможет только ваш аккаунт (чужой ключ получит 403). Публичный GET /voices при этом остаётся строго каталогом.
# GET /api/v1/voices?language=ru&gender=male&limit=200
{
"object": "list",
"total": 152,
"count": 152,
"voices": [
{
"voice": "ru_n16",
"name": "Роман",
"language": "ru",
"gender": "male",
"style": "рассказчик",
"license": "commercial",
"sample_url": "https://golosar.tech/voice-previews/lib/ru_n16.wav"
}
]
}
Свои голоса
Доступ к своим (созданным) голосам
Голос, который вы создали (клон), приватный: он привязан к вашему аккаунту, в общий каталог GET /voices не попадает, и озвучить им может только ваш аккаунт по вашему ключу (чужой ключ → 403). Доступ к своим голосам — по ключу, в три шага:
Шаг 1Создайте API-ключ в кабинете → раздел «API» (нужен тариф Про и выше). Это тот же ключ, что и для синтеза.
Шаг 2GET /api/v1/voices/mine со своим ключом → список только ваших голосов (созданные вами клоны + купленные на маркетплейсе). Поле voice — это id для синтеза.
Шаг 3POST /api/v1/tts с тем же ключом и voice = id вашего голоса → аудио вашим голосом. Язык берётся из самого голоса (запись клона), параметр language для своего голоса игнорируется.
Новый голос, созданный позже, появляется в /voices/mine автоматически — переподключать ключ не нужно. Публичный GET /voices при этом остаётся строго каталогом (приватные голоса в него не подмешиваются).
# Шаг 2 — список своих голосов
curl -H "X-API-Key: <ваш ключ>" https://golosar.tech/api/v1/voices/mine
# Ответ
{
"object": "list",
"count": 2,
"voices": [
{
"voice": "voice-7a6b08",
"name": "Мой голос",
"language": "Russian",
"gender": "male",
"kind": "own",
"sample_url": "https://golosar.tech/voice-previews/voice-7a6b08.wav"
}
]
}
# Шаг 3 — синтез своим голосом (voice = поле из ответа выше)
curl -X POST https://golosar.tech/api/v1/tts -H "X-API-Key: <ваш ключ>" -H "Content-Type: application/json" -d '{"voice":"voice-7a6b08","text":"Привет из моей программы"}' --output out.wav
Доступ
Аутентификация
Все эндпоинты требуют API-ключ: заголовок X-API-Key: <ключ> или Authorization: Bearer <ключ> (кроме GET /api/v1/voices и GET /api/v1/status — открыты). Ключ создаётся в кабинете → раздел «API»; API доступен с тарифа Про и выше (иначе 403). Синтез списывает символы с тарифа ключа — при нулевом балансе возвращается 402. Лимит частоты — по тарифу: Про — 120 запросов/мин, Бизнес — 300, Студия — 600 (фолбэк 60); превышение → 429, заголовок Retry-After.
POST /api/v1/tts
Параметры
voiceid голоса из GET /api/v1/voices. Без параметра — синтез системным голосом по умолчанию (ошибки нет). При НЕИЗВЕСТНОМ id → 403 (голос не найден/недоступен): проверяйте id заранее по /api/v1/voices
textтекст для озвучки; макс. длина зависит от тарифа ключа (обязательно). Поддерживает маркер паузы ‖ — короткая пауза (~0,4 с) точно между словами
languageязык: ru, en, de, fr, es, it, pt, zh, ja, ko (или ru-RU, en-US), либо auto — автоопределение языка по тексту. Для голоса из каталога язык берётся из самого голоса. По умолч. ru
instructэмоция/стиль по-английски, напр. "calm, friendly" (опц.; до 500 символов, дальше обрезается)
emotionэмоция: joyful, excited, tender, calm, sad, serious, tense, angry, afraid, surprised. Работает на любом голосе каталога — эмоцию играет модель; сила подачи преднастроена для каждого голоса. Тембр в целом сохраняется, при яркой эмоции возможен лёгкий сдвиг звучания (размен движка: точность тембра ↔ управляемость интонации). Явный instruct имеет приоритет над emotion (опц.; без параметра — базовая эмоция голоса или нейтрально)
saturationнасыщение/гармоническая «подцветка» тембра (пост-обработка): {"preset":"tube"|"tape"|"air","intensity":0–1} (опц.)
speedтемп речи 0.5–2.0 (опц.)
gain_dbгромкость −24…+24 дБ (опц.)
eqэквалайзер тембра: {"bands":[{"hz":80,"db":4}, …]} (опц.); также принимается сокращённая форма { low, mid, high } (дБ) и произвольные полосы hz строго 0 < hz < 12000 (границы 0 и 12000 исключены — такая полоса молча отбрасывается); db −12…+12
effectпресет звучания: clean (шумоочистка — то же, что отдельный параметр clean:true; указывать что-то одно), radio, audiobook, podcast, phone, cinematic, megaphone, vintage, deep, bright, warm, narrator_warm, intimate, spacious, whisper, concert; характеры: robot, cartoon, chipmunk, monster, villain, echo_hall; студийные: studio_announcer, studio_natural, studio_rich. Премиум-эффекты (характеры, студийные, cinematic, concert, megaphone, vintage) — только на платных тарифах, иначе игнорируются (опц.)
seedцелое 0…2147483647 для детерминированного повтора одной и той же озвучки; вне диапазона — игнорируется, повтор не гарантирован (опц.)
cleantrue — нейро-шумоподавление (отдельный параметр; не путать с effect:"clean", опц.)
backgroundфон/атмосфера: rain, thunder, sea, forest, birds, wind, stream, night, street, cafe, crowd, fire (опц.)
bg_levelгромкость фона 0.05–0.8 (опц., по умолч. 0.25)
lead_silence_msтишина в начале аудио, мс (опц., для агентов; по умолч. 0, макс. 5000)
format"wav" (по умолч.) или "mp3" (опц.)
segmentsальтернатива text — массив [{ text, instruct?, silence?, emotion? }] (до 40 элементов; тот же формат, что в /tts_stream) для пофразовой интонации; куски синтезируются и склеиваются в один файл, эффекты/фон/mp3 накладываются на целое. Символы списываются по сумме длин text сегментов (опц.)
Ответ — бинарный аудиофайл: audio/wav или audio/mpeg (если format=mp3). Передавайте либо text, либо segments.
POST /api/v1/tts_stream
Потоковый синтез
Принимает voice, text, language, instruct, speed, gain_db, eq, effect, seed ИЛИ массив segments (поэлементная интонация). Отдаёт чистый поток PCM (application/octet-stream, chunked; формат: 24 000 Гц, 16 бит, моно, little-endian) для немедленного воспроизведения. Пост-эффекты, применяемые к целому файлу (clean, background/bg_level, lead_silence_ms), и формат mp3 в стриме НЕ поддерживаются — для них используйте POST /api/v1/tts.
Формат segments — массив объектов [{ text, instruct?, silence?, emotion? }], до 40 элементов: text — фрагмент текста; instruct — интонация фрагмента по-английски (до 200 символов); silence — пауза после фрагмента в мс (0–3000; сегмент можно прислать и без текста — только пауза); emotion — эмоция фрагмента: joyful, excited, tender, calm, sad, serious, tense, angry, afraid, surprised. Символы списываются по сумме длин text всех сегментов.
# POST /api/v1/tts_stream → поток PCM (application/octet-stream, chunked)
{
"voice": "ru_n16",
"text": "Привет! Это потоковый синтез.",
"language": "ru"
}
POST /api/v1/voices/clone
Создание голоса
nameназвание голоса (обязательно; ≤80 символов — длиннее молча обрезается)
audio_b64запись-образец в base64, ≤10 МБ (обязательно)
ref_textтекст образца — должен совпадать с записью слово-в-слово (обязательно; ≤2000 символов — длиннее молча обрезается, поэтому для длинного образца укладывайтесь в лимит, иначе транскрипт перестанет совпадать с аудио и качество клона упадёт)
consentстрока согласия — передавайте ровно "voice-data-consent,privacy" (данные голоса, 152-ФЗ); без неё — 400 (обязательно)
languageязык образца, полное имя (Russian, English…) или ISO-код; по умолч. Russian (опц.)
Поле voice из ответа передавайте в POST /tts. Значение voice ниже — иллюстративный пример; реальный идентификатор приходит в ответе. Создание своего голоса ПО API требует доступа к API (тариф Про и выше) и учитывает лимит голосов тарифа.
# Ответ — 200 OK (значение voice — пример)
{
"ok": true,
"voice": "usr_a1b2c3",
"name": "Мой голос",
"language": "Russian"
}
POST /api/v1/transcribe
Расшифровка
audio_b64аудио в base64; рассчитано на короткий фрагмент (обязательно)
languageтолько ПОЛНОЕ имя языка: Russian, English, German, French, Italian, Spanish, Portuguese, Chinese, Japanese, Korean; бета (без гарантии): Ukrainian, Polish, Dutch, Greek, Bulgarian, Czech, Romanian, Slovak, Slovenian, Serbian, Swahili (ISO-коды здесь НЕ принимаются, в отличие от /tts; без параметра — автоопределение) (опц.)
размераудио ≤ ~30 МБ в base64 (иначе 413, code=audio_too_large); пустое/слишком короткое — 400 (code=no_audio)
Списываются символы по тарифу (≈1 мин аудио = 1000 символов, минимальная тарификация — 3 секунды), учитывается месячный лимит минут расшифровки тарифа.
# Ответ
{
"text": "Расшифрованный текст фрагмента.",
"language": "Russian"
}
GET /api/v1/status · POST /api/v1/warmup
Статус и прогрев
GET /api/v1/status (без ключа) — готовность движка для real-time. POST /api/v1/warmup (с ключом; символы НЕ списывает) прогревает движок перед серией звонков.
# GET /api/v1/status
{
"ready": true,
"model_ready": true,
"engine_up": true,
"latency_ms": 42
}
# POST /api/v1/warmup
{
"ok": true,
"warmed": true,
"warm_ms": 318
}
Ответ
Заголовки и поле code
Content-Typeaudio/wav или audio/mpeg (по параметру format); для /tts_stream — application/octet-stream
X-Effects-Failedэффекты, которые НЕ применились (на движке или срезаны тарифом), через запятую — звук вернётся без них
X-CacheHIT / MISS — был ли ответ отдан из кэша (ускорение). На биллинг НЕ влияет: по API-ключу каждый успешный синтез тарифицируется одинаково, и на HIT, и на MISS (деньги за результат)
Retry-Afterпри 429 — через сколько секунд повторить запрос
Поле code в теле ошибки (машиночитаемо): plan_required — нужен тариф выше; voice_limit — лимит голосов тарифа; plan_quota — исчерпан месячный лимит минут расшифровки; email_unverified — подтвердите email; voice_conflict — имя голоса уже занято (при создании голоса); insufficient_balance — нет символов на балансе ключа (402); voice_access — нет доступа к голосу / неизвестный id (403); audio_too_large — файл больше лимита (413); bad_json / no_audio — битое тело/нет аудио (400); mp3_unavailable — MP3-кодировщик недоступен (503); rate_limited — превышен лимит частоты (429). Список неполный — ориентируйтесь на HTTP-код, поле code уточняет причину.
Коды ответов
Ошибки
200Успех — тело ответа содержит аудиофайл
400Битый JSON, пустой текст, текст длиннее лимита тарифа (символов на запрос) или неизвестный движку язык
401Нет или неверный API-ключ (заголовок X-API-Key / Authorization)
402Недостаточно символов на балансе ключа — пополните тариф
403Функция недоступна на текущем тарифе (доступ к API, включая создание голоса, — с Pro и выше) или нет доступа к голосу
409Конфликт (voice_conflict): голос с таким именем уже есть — при создании голоса укажите другое имя
413Слишком большой файл: создание голоса — образец >10 МБ (base64); расшифровка — аудио > ~30 МБ (base64, code=audio_too_large)
429Превышен лимит частоты. Синтез И расшифровка (POST /transcribe) — по тарифу ключа, каждый эндпоинт своим счётчиком (Про 120, Бизнес 300, Студия 600). Отдельные лимиты: создание голоса (clone) — 10/мин на аккаунт, GET /voices — 120/мин на IP, GET /status — 60/мин на IP, warmup — 20/мин на аккаунт (несколько ключей одного аккаунта делят лимит). Смотрите заголовок Retry-After
502Сбой обработки на стороне сервиса (конвертация в MP3 или ответ движка расшифровки/клонирования) — повторите запрос
503Движок спит/недоступен или сервис перегружен — повторите через несколько секунд. Отдельный случай: при format=mp3 — «MP3-кодировщик недоступен на сервере» (проверяется до синтеза, символы не списываются); повтор не поможет — используйте format=wav или напишите в поддержку
Тело ошибки — JSON { "error": "описание" } (иногда с полем code, например plan_required). Символы при неуспехе не списываются. Исключение — обрыв потока /tts_stream на середине: списываются только символы за фактически доставленное аудио, остаток возвращается.
Каталог
Эффекты и фоны
Параметр effect — один пресет на запрос. Бесплатные доступны всем; премиум — на платных тарифах.
Подача (free)radio — сухой эфир · audiobook — аудиокнига · narrator_warm — тёплый рассказчик · podcast — подкаст · phone — телефон · intimate — близко · spacious — простор · whisper — шёпот · deep — ниже · bright — ярче · warm — теплее
Студийные (премиум)studio_announcer — дикторский эфир · studio_natural — естественный студийный · studio_rich — насыщенный «дорогой» · cinematic — кино · concert — зал · megaphone — рупор · vintage — винтаж
Характеры (премиум)robot — робот · cartoon — мультяшный · chipmunk — бурундук · monster — монстр · villain — злодей · echo_hall — эхо-зал
Фоны (background)Природа: rain (дождь) · thunder (гроза) · sea (море) · forest (лес) · birds (птицы) · wind (ветер) · stream (ручей) · night (ночь). Город: street (улица) · cafe (кафе) · crowd (толпа). Уют: fire (камин). Громкость — bg_level 0.05–0.8
eq (тембр)8 полос: 80, 160, 300, 600, 1500, 3500, 6500, 10500 Гц, каждая −12…+12 дБ. Пример: {"bands":[{"hz":80,"db":-4},{"hz":3500,"db":3}]} — убрать гул, добавить чёткости
Квоты
Лимиты
Частота запросовсинтез и расшифровка (POST /transcribe) — по тарифу ключа, у каждого эндпоинта свой счётчик: Про — 120/мин, Бизнес — 300/мин, Студия — 600/мин (фолбэк 60). Отдельно: создание голоса (POST /voices/clone) — 10/мин на аккаунт; GET /voices — 120/мин на IP; GET /status — 60/мин на IP; warmup — 20/мин на аккаунт. Превышение → 429 + Retry-After
Длина текстамакс. символов на один POST /api/v1/tts зависит от тарифа ключа
Баланс символовсинтез списывает символы с тарифа ключа; при нулевом балансе — 402
Расшифровка≈1 мин аудио = 1000 символов; учитывается месячный лимит минут расшифровки тарифа
Размер файласоздание голоса: образец ≤10 МБ (base64), иначе 413. Расшифровка: аудио ≤ ~30 МБ (base64), иначе 413
Пример
Полный запрос
POST /api/v1/tts
{
"voice": "ru_n16",
"text": "Сегодня отличная погода.",
"language": "ru",
"instruct": "calm, friendly",
"speed": 1.0,
"effect": "podcast",
"eq": { "bands": [ { "hz": 3500, "db": 3 } ] },
"background": "rain",
"bg_level": 0.2,
"format": "mp3"
}
→ 200 OK, Content-Type: audio/mpeg (бинарный файл)