Руководство по синтезу речи (TTS)

Руководство по синтезу речи (TTS)

POST /v1/audio/speech совместим с OpenAI-compatible форматом: отправьте JSON и получите аудиофайл в бинарном виде. Семейство ElevenLabs включает elevenlabs/eleven-v4, eleven-v4-turbo, eleven-v3, eleven-v3-conversational, eleven-multilingual-v2, eleven-flash-v2.5, eleven-flash-v2, eleven-turbo-v2.5, eleven-turbo-v2. Актуальный список: GET /v1/models?output_modalities=speech. GET /v1/models по умолчанию возвращает только текстовые модели; добавьте ?output_modalities=speech (или all), чтобы увидеть список.

Параметры

Семь настроек голоса выше необязательны; если их не указывать, ничего не меняется. Значение вне диапазона даёт 400 и не отправляется и не тарифицируется. Заголовок ответа X-Voice-Settings показывает, были ли использованы ваши настройки: applied — использованы; ignored — ответил резервный маршрут, поэтому настройки не использованы (аудио всё равно создаётся); нет заголовка — вы не передавали настроек голоса. Пример: stability 0 читает выразительнее, 1 — ровнее.

Правила выбора голоса

Модели ElevenLabs (elevenlabs/…) принимают одно из этих имён голосов (регистр не важен): george, sarah, adam, alice, bella, bill, brian, callum, charlie, chris, daniel, eric, harry, jessica, laura, liam, lily, matilda, river, roger, will. Для моделей ElevenLabs voice можно опустить (по умолчанию george). Любое другое значение даёт 400 invalid_voice. Ваш собственный голос (voice_…) описан в разделе «Собственные голоса» ниже.

Имена голосов OpenAI-style, например alloy, echo или nova, работают только с моделями, где они перечислены. Проверьте голоса на странице модели.

Собственные голоса (клонирование) открываются поэтапно: см. раздел «Собственные голоса» ниже (POST /v1/voices). Пока они не включены для вашего аккаунта, используйте одно из 21 готовых имён выше или публичный voice ID.

Встроенные голоса

Укажите в voice одно из имён ниже (строчными буквами). У каждого голоса есть короткий собственный пример, а GET /api/v1/audio/voices возвращает полный список (пол, возрастная группа, акцент, стиль и ссылки на примеры).

?lang= (en, zh-TW, zh-CN; по умолчанию Accept-Language) выбирает только язык description. Ссылки на примеры от него не зависят: preview_urls.en (то же, что preview_url) — английский клип, preview_urls.zh (то же, что preview_url_zh) — китайский.

Теги эмоций и действий (audio tags)

Пишите теги в квадратных скобках прямо в input, например [laughs], [whispers], [excited], [sighs], [crying], [curious] или [softly]. Теги передаются модели в точности как набраны и задают манеру произнесения следующих слов. Даже если текст не на английском, оставляйте теги на английском.

curl https://api.bazaarlink.ai/v1/audio/speech \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs/eleven-v3","input":"[laughs] That was actually funny. [whispers] Do not tell anyone.","voice":"george","response_format":"mp3"}' \
  --output audio-tags.mp3

Поддерживаются моделью elevenlabs/eleven-v3 и семейством elevenlabs/eleven-v4. Другие модели речи не интерпретируют теги и могут прочитать скобки вслух, поэтому сначала проверьте короткую фразу.

Теги входят в число символов input и тарифицируются так же, как остальной текст.

Форматы вывода

Если response_format опущен, используется mp3 (Content-Type audio/mpeg); pcm (audio/pcm, сырой 16-bit PCM) тоже работает. API принимает opus, aac, flac и wav, но модели ElevenLabs сейчас отклоняют их с 400. Сохраняйте файл по заголовку Content-Type ответа.

Стоимость

Синтез речи оплачивается по числу символов ввода. Цена за символ указана на странице модели в /models и в GET /v1/models как pricing.character. На странице модели она показана за миллион символов.

Примеры

curl https://api.bazaarlink.ai/v1/audio/speech \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs/eleven-flash-v2.5","input":"Hello from BazaarLink.","voice":"george","response_format":"mp3"}' \
  --output speech.mp3

Частые ошибки

Полный справочник параметров: Синтез речи

Синтез речи

Преобразует текст в аудио по ID модели из /v1/models?output_modalities=speech. Оплата — по цене за миллион символов на странице модели. Аудио полностью буферизуется и затем возвращается бинарными данными; пошаговая потоковая выдача не поддерживается. Поля управления маршрутизацией provider, transforms, route, service_tier и preset игнорируются.

curl https://api.bazaarlink.ai/v1/audio/speech \
  -H "$BAZAARLINK_AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{"model":"<speech-model-id>","input":"Hello","voice":"alloy","response_format":"mp3"}' \
  --output speech.mp3

# Voice settings (elevenlabs/* models; the X-Voice-Settings response header says applied or ignored)
curl -D - https://api.bazaarlink.ai/v1/audio/speech \
  -H "$BAZAARLINK_AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs/eleven-v4","input":"Hello","voice":"george","stability":0.4,"similarity_boost":0.8,"style":0.2,"use_speaker_boost":true,"language_code":"en","audio_effects":{"distance":0.3}}' \
  --output speech.mp3