Как подключить ElevenLabs для озвучки текста

Результат: после выполнения инструкции вы подключите ElevenLabs для озвучки текста через API, получите voice_id, отправите первый запрос и сохраните аудиофайл speech.mp3. Базовый путь ниже построен на официальном REST API, поэтому его проще всего повторить без привязки к часто меняющимся версиям SDK.

Редакционное ограничение: supplied source pack точно фиксирует API, маршрутизацию, модели и тарифные оговорки, но не даёт стабильных названий элементов кабинета для создания ключа. Поэтому интерфейсная часть описана на уровне действия, а воспроизводимые шаги даны через переменные окружения и HTTP-запросы.

Какой способ подключения выбрать

Пошаговая инструкция

Ниже — минимальный рабочий путь для запроса TTS. Примеры команд даны для bash-совместимой оболочки; в PowerShell используйте ту же логику, но адаптируйте кавычки.

1. Создайте API-ключ ElevenLabs.

   Для работы с API ElevenLabs нужен API-ключ, и каждый запрос должен передавать его в заголовке xi-api-key. По документации ключи можно ограничивать по scope, квоте кредитов и IP-адресам. Не публикуйте ключ на клиентской стороне и не вшивайте его в браузерный JavaScript.

   Ожидаемый результат: у вас есть рабочий ключ, который вы готовы сохранить в переменной окружения или секрет-хранилище.

2. Сохраните ключ в переменной окружения ELEVENLABS_API_KEY.

   Официальный quickstart для Python использует именно эту переменную. Это удобно и для REST, потому что ключ не остаётся в истории коммитов и конфигов приложения.

   export ELEVENLABS_API_KEY='YOUR_API_KEY'

   Для PowerShell:

   $env:ELEVENLABS_API_KEY='YOUR_API_KEY'

   Ожидаемый результат: ключ доступен в текущей сессии терминала, а в команде запроса его можно подставлять как $ELEVENLABS_API_KEY.

3. Зафиксируйте базовый URL API.

   По умолчанию региональная маршрутизация работает через api.elevenlabs.io. Если вам нужно жёстко использовать США, официальный гайд рекомендует api.us.elevenlabs.io. Для Enterprise isolated environments используются отдельные URL и отдельные API-ключи; это не обычная настройка для всех аккаунтов.

   export ELEVENLABS_BASE_URL='https://api.elevenlabs.io'

   Если нужен принудительный US endpoint:

   export ELEVENLABS_BASE_URL='https://api.us.elevenlabs.io'

   Ожидаемый результат: вы заранее понимаете, через какой endpoint идёт подключение и какой регион ожидаете увидеть в заголовке x-region.

4. Получите доступный voice_id через список голосов.

   Официальный способ найти голос для TTS — вызвать список доступных голосов через GET /v2/voices. Не копируйте случайный voice_id из стороннего примера: доступность конкретного голоса зависит от тарифа и аккаунта.

   curl -s -X GET "$ELEVENLABS_BASE_URL/v2/voices" 
     -H "xi-api-key: $ELEVENLABS_API_KEY"

   Просмотрите JSON-ответ и скопируйте тот voice_id, который реально доступен вашему аккаунту. Для пользователей free tier голоса Voice Library недоступны через API; для некоторых голосов действует paid-only доступ и credit multipliers.

   Ожидаемый результат: у вас есть конкретный voice_id для следующего шага.

5. Отправьте первый запрос на озвучку текста.

   Основной TTS endpoint — POST /v1/text-to-speech/:voice_id. В официальном примере для API используется model_id eleven_multilingual_v2, а если не передавать output_format, по документации default — mp3_44100_128.

   curl -s -D headers.txt -X POST "$ELEVENLABS_BASE_URL/v1/text-to-speech/YOUR_VOICE_ID" 
     -H "xi-api-key: $ELEVENLABS_API_KEY" 
     -H "Content-Type: application/json" 
     -d '{
       "text": "Привет! Это тест озвучки через ElevenLabs API.",
       "model_id": "eleven_multilingual_v2"
     }' 
     --output speech.mp3

   Подставьте ваш реальный voice_id вместо YOUR_VOICE_ID. Ключевой результат этого шага — файл speech.mp3 и отдельный файл headers.txt с HTTP-заголовками.

   Ожидаемый результат: в рабочей папке появляется speech.mp3; размер файла больше нуля, а в headers.txt есть серверные заголовки ответа.

6. Проверьте аудио и заголовки ответа.

   Откройте speech.mp3 любым локальным плеером. Если звук воспроизводится, базовое подключение ElevenLabs для озвучки текста выполнено. Для дополнительной диагностики откройте headers.txt и найдите x-region: по нему можно понять, куда реально маршрутизирован запрос.

   Если позже перейдёте на официальный SDK, документация показывает отдельный способ читать raw response headers через with_raw_response.convert(), включая character-cost, request-id и x-trace-id. Для первого подключения REST-путь обычно удобнее, потому что вы сразу видите и бинарный файл, и сетевые заголовки.

   Ожидаемый результат: вы слышите синтезированную речь и, при необходимости, видите диагностические заголовки ответа.

Если вам нужен Python или Node вместо REST

Официальный quickstart для Python рекомендует сохранить ключ в ELEVENLABS_API_KEY, установить elevenlabs и python-dotenv, затем создать client и вызвать text_to_speech.convert. В этом гайде успешный результат — слышимый звук из динамиков. Для Node.js и TypeScript используйте официальный репозиторий elevenlabs-js; он подходит для веб-сервисов и серверных приложений.

Как проверить, что всё работает

• Файл создан: после шага с POST-запросом в каталоге есть speech.mp3.
• Файл воспроизводится: вы слышите речь, а не тишину или повреждённый контейнер.
• Маршрутизация понятна: в headers.txt есть x-region, если вы проверяете регион backend-соединения.
• Голос доступен аккаунту: использованный voice_id взят из ответа GET /v2/voices, а не из чужого примера.
• Модель выбрана осознанно: для первого запуска вы использовали eleven_multilingual_v2 из официального примера, а для low-latency сценариев отдельно протестируете Flash v2.5.

Частые ошибки и исправления

• ❌ Запрос не проходит из-за авторизации.
  ✅ Решение: проверьте, что ключ реально передаётся в заголовке xi-api-key, а не в теле запроса. Убедитесь, что в переменной окружения нет лишних пробелов и что ключ не ограничен IP или scope так, что ваш запрос блокируется.
• ❌ voice_id не работает или голос недоступен.
  ✅ Решение: сначала получите список голосов через GET /v2/voices и берите идентификатор только из ответа вашего аккаунта. Помните, что Voice Library недоступна через API для free tier, а часть голосов относится к paid-only и может иметь credit multipliers.
• ❌ Нужен другой аудиоформат, но запрос не даёт ожидаемый результат.
  ✅ Решение: для первого запуска не переопределяйте output_format и используйте default. Если вам нужен MP3 192 kbps, PCM или WAV 44.1 kHz, сначала проверьте ограничения тарифа: по pricing-странице MP3 192 kbps требует Creator+, а PCM и WAV 44.1 kHz — Pro+.
• ❌ Регион обработки не тот, который вы ожидали.
  ✅ Решение: посмотрите заголовок x-region. Если нужен жёсткий US endpoint, используйте api.us.elevenlabs.io. Для Enterprise isolated environments применяются отдельные URL и отдельные API-ключи.
• ❌ Качество и задержка не подходят под задачу.
  ✅ Решение: выбор модели зависит от сценария. Официальные материалы отмечают Flash v2.5 как low-latency вариант для real-time use cases, а Multilingual v2 — как вариант с более высоким качеством. Eleven v3 уже в general availability, но его стоит тестировать под вашу задачу отдельно.

Безопасность и ограничения

• Не храните API-ключ на фронтенде. Документация прямо предупреждает, что ключ нельзя раскрывать на клиентской стороне.
• Используйте ограничения ключа. Если сценарий рабочий, задайте scope, кредитную квоту и IP-ограничения для снижения риска утечки.
• Учитывайте оплату. TTS тарифицируется по символам в USD, а точные ставки, кредитные лимиты и ограничения тарифов могут меняться.
• Не рассчитывайте на любой голос. Доступность конкретного voice_id зависит от подписки, правил paid-only и credit multipliers.
• Проверяйте регион и residency. Глобальная маршрутизация по умолчанию не означает фиксированный регион; для Enterprise data residency есть отдельные URL и отдельные ключи.
• Не переоценивайте стабильность SDK-примеров. Репозитории Python и JS обновляются часто, поэтому для диагностики первого запуска REST-путь надёжнее: он сразу показывает и заголовки, и бинарный результат.

Практический вердикт: если ваша цель — просто подключить ElevenLabs для озвучки текста и быстро убедиться, что всё работает, начинайте с REST-запроса из этой инструкции. Уже после успешного speech.mp3 имеет смысл переносить интеграцию в Python или Node SDK.

Что делать дальше

• Если вам нужна озвучка через веб-интерфейс без API, откройте Как озвучить текст в ElevenLabs.
• Если вы настраиваете сразу несколько AI-интеграций и хотите увидеть похожий серверный паттерн с секретами и первым запросом, посмотрите Как подключить OpenAI API и отправить первый запрос.
• Если следующий шаг — собрать озвучку в мультимедийный пайплайн, пригодится разбор лучших нейросетей для видео из текста.

Источники

• Releases · elevenlabs/elevenlabs-js · GitHub
• ElevenAPI Pricing for creators and businesses of all sizes

• API Authentication | ElevenLabs Documentation
• ElevenAPI quickstart | ElevenLabs Documentation
• Create speech | ElevenLabs Documentation
• List voices | ElevenLabs Documentation
• Voice Library | ElevenLabs Documentation
• Introduction | ElevenLabs Documentation
• Latency optimization | ElevenLabs Documentation
• Data residency | ElevenLabs Documentation
• ElevenAPI Pricing for creators and businesses of all sizes
• GitHub – elevenlabs/elevenlabs-python
• GitHub – elevenlabs/elevenlabs-js
• Eleven v3 is Now Generally Available

Вопросы и ответы

Можно ли подключить ElevenLabs без Python и Node SDK?

Да. Для первого запуска достаточно REST API: получить voice_id, передать ключ в xi-api-key и вызвать POST /v1/text-to-speech/:voice_id.

Какой endpoint использовать по умолчанию?

По умолчанию используется api.elevenlabs.io с глобальной маршрутизацией. Если вам нужен жёсткий US endpoint, используйте api.us.elevenlabs.io. Для Enterprise isolated environments нужны отдельные URL и отдельные ключи.

Какую модель выбрать для первого запроса?

Для первого воспроизводимого запуска удобно взять eleven_multilingual_v2, потому что она используется в официальном примере Create speech. Для low-latency сценариев официальные материалы по-прежнему выделяют Flash v2.5, а Eleven v3 стоит отдельно тестировать под свою задачу.

Почему голос из чужого примера не работает у меня?

Потому что доступность голосов зависит от вашего аккаунта и тарифа. Получайте список через GET /v2/voices и выбирайте только те voice_id, которые реально возвращаются вам. Для free tier Voice Library через API недоступна.

Сколько стоит озвучка через ElevenLabs API?

API-тарификация TTS идёт по символам в USD. Точные цены, кредитные лимиты и ограничения форматов меняются, поэтому их нужно проверять на официальной pricing-странице перед запуском в продакшн.