API для озвучки текста: как подключить за 10 минут

Чтобы озвучить текст из своего кода, нужны ключ и один POST-запрос. Это обычный REST, SDK не понадобится. Ниже весь путь от ключа до обработки ошибок.

Шаг 1. Получите ключ

API открывается с тарифа Про: 790 ₽ в месяц, 300 000 символов. На тарифах Free и Старт его нет, и ключ там не создать.

Ключ создаётся в кабинете, в разделе «API». Показывается он один раз: полностью мы его не храним. Сохраните ключ сразу, а если потеряете, выпустите новый там же.

Передавать ключ можно заголовком X-API-Key или Authorization: Bearer.

Шаг 2. Выберите голос

Каталог открыт, ключ для него не нужен. Искать можно по названию и идентификатору (q), фильтровать по языку, полу и роли (language, gender, role).

curl "https://golosar.tech/api/v1/voices?q=dk2510_30"

Ответ, часть полей опущена:

{
  "object": "list",
  "total": 1,
  "count": 1,
  "voices": [
    {
      "voice": "dk2510_30",
      "name": "Семён",
      "language": "ru",
      "gender": "male",
      "style": "весёлый",
      "use_case": "реклама",
      "license": "commercial",
      "badge": null
    }
  ]
}

В запрос синтеза идёт значение поля voice. В ответе есть и sample_url, ссылка на пример звука. Если строите выбор голоса для своих пользователей, проверяйте license и badge: голос с noncommercial подходит только для проб, а с меткой soon вернёт ошибку.

Шаг 3. Отправьте текст

Обязательны два поля: voice и text.

curl -X POST https://golosar.tech/api/v1/tts \
  -H "X-API-Key: ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"voice":"dk2510_30","text":"Привет! Это Голосарь."}' \
  -D - --output golos.wav

То же на Python:

import os, requests

r = requests.post(
    "https://golosar.tech/api/v1/tts",
    headers={"X-API-Key": os.environ["GOLOSAR_KEY"]},
    json={"voice": "dk2510_30", "text": "Привет! Это Голосарь."},
)
if r.ok:
    with open("golos.wav", "wb") as f:
        f.write(r.content)
else:
    print(r.status_code, r.json()["code"], r.json()["error"])

В ответ приходит сам аудиофайл, а не JSON. Главное о нём лежит в заголовках:

HTTP/1.1 200 OK
Content-Type: audio/wav
X-Chars-Charged: 21
X-Sample-Rate: 24000

X-Chars-Charged показывает, сколько символов списано. X-Sample-Rate лучше читать, а не зашивать в код: частота зависит от линии голоса, и ошибка слышна как ускоренная или замедленная речь.

По умолчанию это WAV, 16 бит, моно. Для MP3 добавьте "format":"mp3". Для телефонии есть response_format: g711_alaw_8k, g711_ulaw_8k, g722_16k, opus, pcm_s16le_24k. Язык голоса из каталога определяется самим голосом, поле language здесь можно не передавать.

Плюс перед ударной гласной («зам+ок») задаёт ударение, не читается вслух и не оплачивается. Маркер ‖1.5‖ ставит паузу на полторы секунды.

Шаг 4. Обработайте ошибки

Ошибка приходит в JSON с полями error и code. Например, на неверный ключ сервер отвечает статусом 401:

{"error":"Invalid or revoked API key.","code":"api_key_invalid"}

• 400: ошибка в запросе, причина в code.
• 401: ключ не передан или недействителен.
• 402: insufficient_balance, не хватает символов.
• 403: нет прав: тариф без API, неподтверждённая почта, голос не найден или недоступен.
• 429: rate_limited или concurrency_limit, слишком много запросов.
• 502 и 503: сбой синтеза или движок занят. При 502 символы возвращаются.

Повторять стоит только временные ошибки: 429 по заголовку Retry-After, 502 и 503 с растущей паузой, две-четыре попытки. Ключей идемпотентности нет: каждый успешный повтор спишет символы заново, а память озвучки из редактора в API не работает. Чтобы повтор дал тот же звук, передавайте одинаковый seed.

Какие лимиты учесть

На тарифе Про это 120 запросов в минуту, 20 000 символов на запрос и две задачи одновременно. На Бизнесе 300 запросов в минуту, на Студии 600. Счётчик частоты общий на аккаунт, поэтому второй ключ её не удвоит, но у каждого метода счётчик свой.

Длинный текст сервис сам режет по предложениям и склеивает в один файл. Синхронно уходит до пяти частей, сверх этого запрос вернёт 400 text_too_long_for_sync без списания. Тогда передайте текст массивом segments или несколькими запросами.

Что ещё пригодится

• POST /api/v1/tts_stream отдаёт PCM по мере синтеза, это удобно для голосовых интерфейсов.
• GET /api/v1/status открыт без ключа и показывает готовность движка в поле ready.
• POST /api/v1/audio/speech принимает запрос в формате OpenAI, текст в поле input.

Все параметры, эффекты и коды ошибок описаны в документации API, а обзор сценариев есть на странице API синтеза речи.

Попробуйте сами — бесплатный стартовый пакет символов при регистрации.