Как интегрировать Text to Speech в ваши приложения

Чтобы интегрировать Text to Speech в свои приложения, создайте ключ API, установите ElevenLabs SDK, отправьте текст на эндпоинт TTS с указанием голоса и модели, а затем воспроизведите полученное аудио.

В этом руководстве пошагово рассматриваются эти действия на Python и TypeScript, демонстрируется выбор оптимального пути интеграции TTS и описываются способы устранения распространенных ошибок.

Что такое API синтеза речи (Text to Speech)?

API Text to Speech позволяет разработчикам программно преобразовывать написанный текст в звучащую естественным образом речь без необходимости самостоятельно размещать модель TTS. Интегрировав TTS API в приложение, разработчики просто отправляют запрос к API и получают обратно аудиофайл, что позволяет с легкостью добавить голосовой слой в любые приложения.

Лучшие API для синтеза речи, такие как решение от ElevenAPI, предоставляют детальный контроль над звучанием конечного аудио: от выбора голоса для озвучивания фрагмента текста до передаваемых им эмоций. В зависимости от сценария использования вашего приложения вы также сможете выбирать между пакетной обработкой (batch) и потоковой передачей (streaming) для создания аудиофрагментов.

Как работает запрос к API синтеза речи

Когда вы обращаетесь к TTS API, за кулисами происходит несколько шагов для подготовки вашего аудио.

Вот как работает запрос к API Text to Speech:

• Ваше приложение отправляет текст на эндпоинт Text to Speech вместе с выбранными вами голосом и моделью.
• API генерирует речь и возвращает аудио в запрошенном вами формате вывода, например MP3.
• Ваше приложение воспроизводит аудио или сохраняет его в виде файла.

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

Контрольный список того, что вам понадобится перед началом интеграции TTS в приложения

Прежде чем интегрировать Text to Speech в свои приложения, убедитесь, что у вас есть следующее:

• Учетная запись ElevenLabs. Зарегистрироваться можно за несколько минут.
• Терминал и редактор кода.
• Установленные на вашем компьютере Python 3 или Node.js.
• Способ воспроизведения получаемого аудио.

Имея все это под рукой, вы готовы добавлять TTS в свое приложение.

С ElevenAPI интеграция TTS API в ваше приложение займет всего несколько минут. Если вы уже зарегистрировали аккаунт, можете сразу перейти к описанным ниже шагам. Если нет, не забудьте

Шаги выглядят следующим образом:

• Создать ключ API
• Установить SDK
• Сделать первый запрос
• Запустить его

Давайте разберем их подробнее.

Создать ключ API

Получите ключ API в панели управления ElevenLabs API. После нажатия кнопки «Create Key» вы сможете настроить тип создаваемого API. Для данного сценария убедитесь, что для TTS включен доступ ('Access').

Скопируйте ключ API и вставьте его в качестве переменной окружения в файл .env (или непосредственно в конфигурацию приложения в зависимости от его архитектуры). Хранение в файле .env — эффективный способ сохранить ключ в тайне и позволить вашему скрипту загружать его во время выполнения.

Хотите поручить настройку вашему агенту кодирования? Вставьте в него следующую команду: npx -y @elevenlabs/cli@latest onboard init. Интерфейс командной строки ElevenLabs откроет ваш браузер для входа в систему, сохранит ключ в файл окружения вашего проекта и поможет агенту пройти оставшиеся шаги. Для npx требуется Node.js. Подробности см. в кратком руководстве.

Установить SDK

При настройке API Text to Speech необходимо установить два основных пакета. Первый — это ElevenLabs SDK, который будет обрабатывать вызовы API. Второй — dotenv, который загрузит ваш ключ API из файла .env, настроенного на первом шаге.

Если вы работаете через CLI, обратитесь к нашей документации по TTS API, где вы найдете более конкретные инструкции и доступные параметры.

Вот как установить SDK и dotenv для вашего TTS API с помощью Python и TypeScript.

Python

TypeScript

Сделать первый запрос

Затем создайте клиент. Клиент — это объект, который оборачивает ElevenAPI. Создайте файл .py или .mts в зависимости от используемого языка программирования.

На результат влияют четыре основных параметра:

• Voice ID: в библиотеке голосов ElevenLabs доступно более 17 500 голосов. Выберите голос, который лучше всего представляет ваше приложение или подходит под ваш сценарий. В приведенных ниже блоках кода быстрого старта мы используем «George», имеющий идентификатор голоса «JBFqnCBsd6RMkjVDRZzb»
• Text: строка текста, которую модель TTS в ElevenAPI должна преобразовать в аудиофайл.
• Model ID: конкретная модель, используемая для генерации аудио. В примере ниже мы использовали eleven_v4, но вы также можете выбрать любую другую нашу модель Text to Speech, если она лучше подходит под ваши задачи. Например, для уменьшения задержки можно выбрать Eleven Flash v2.5 (eleven_flash_v2_5 в поле идентификатора модели).
• Output format: задайте кодирование аудио, которое вы хотите получить от TTS API. По умолчанию возвращается формат mp3, но вы можете переключиться на такие форматы, как ulaw или pcm.

Вот как выглядят эти файлы интеграции TTS API на Python и TypeScript. В обоих примерах ниже используется модель eleven_v4.

Python

TypeScript

cURL

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

Запустить его

Теперь вы готовы запустить файл TTS API. Выполните одну из следующих команд в зависимости от того, пишите ли вы на Python или TypeScript.

Python

TypeScript

Вы должны услышать воспроизведение аудио через динамики. В примере с cURL обязательно откройте файл speech.mp3.

Устранение распространенных ошибок интеграции TTS

Если ваш первый запрос завершился неудачно, сравните полученный код состояния со следующим списком возможных ошибок.

Статус

Значение

Что делать

400 или 404

validation_error, invalid_request или not_found: запрос недействителен, либо голос или другой ресурс не существует

Исправьте запрос перед повторной попыткой. Поле param в описании ошибки указывает на недействительное значение. Типичные причины: неверный идентификатор голоса (invalid_voice_id или voice_not_found для несуществующего ID), неподдерживаемая модель или формат вывода, а также слишком длинный текст (text_too_long).

401, 402 или 403

authentication_error, payment_required или authorization_error: проблемы с вашим ключом API, балансом или доступом

Для 401 проверьте ключ API и заголовок xi-api-key. Для 402 пополните баланс (insufficient_credits). Для 403 убедитесь, что ваш тарифный план включает эту функцию или модель (feature_not_available или model_access_denied).

429

rate_limit_error: превышено ограничение частоты запросов (rate_limit_exceeded) или параллельных запросов (concurrent_limit_exceeded)

При превышении лимита частоты повторите запрос с экспоненциальной задержкой. При превышении лимита параллельных запросов дождитесь завершения текущих запросов перед отправкой новых либо перейдите на тарифный план с более высоким лимитом.

500 или 503

internal_error или service_unavailable: проблема на стороне ElevenLabs, что случается редко

Подождите немного и повторите попытку. Если ошибка 500 не исчезает, обратитесь в службу поддержки.

Полный список ошибок см. на справочной странице ошибок (Errors).

Преимущества интеграции API Text to Speech

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

Вот преимущества интеграции TTS API в ваше приложение:

• Доступность: Синтезированная речь предоставляет новый способ взаимодействия с вашим приложением, делая его доступным для тех, кому трудно читать с экрана.
• Вовлеченность: Функции чтения вслух и совместного прослушивания позволяют пользователям воспринимать контент во время выполнения других задач, что становится основным способом потребления информации.
• Голосовые интерфейсы: Голосовые ответы придают чат-ботам и внутриигровым или внутриприложенческим помощникам естественное звучание при общении с пользователями.
• Многоязычный охват: Eleven v4 поддерживает более 90 языков, что позволяет вашей интеграции обслуживать аудиторию по всему миру.

Учитывая простоту настройки, интеграция TTS API в ваше приложение является мощным способом сделать его более интерактивным и выразительным.

Выбор правильного пути интеграции и модели

Хотя ElevenAPI является одним из самых быстрых и простых способов добавления голоса в приложение, в зависимости от ваших потребностей можно выбрать и другие варианты.

Вот несколько различных методов интеграции TTS на выбор:

Путь

Лучше всего подходит для

Что вам нужно

Синтез речи в браузере (Web Speech API)

Простые прототипы для браузера, использующие локальные голоса

Только код для браузера

Приложения, где требуются стабильные, высококачественные голоса и контроль над выводом

API-ключ и SDK или HTTP-запрос

Интеграция речи в статьи или веб-страницы, как это сделано в TIME.

Виджет или плагин для CMS

Двусторонние голосовые разговоры

Агент, настроенный на платформе

Если вы выбираете ElevenAPI, вам также потребуется выбрать модель для включения в ваш запрос. Вот краткое руководство по доступным моделям ElevenLabs TTS:

Модель

Лучше всего подходит для

Языки

eleven_v4

Наиболее выразительная речь

90+

eleven_flash_v2_5

Использование в реальном времени, агенты и большие объемы работы

eleven_multilingual_v2

Стабильное высококачественное повествование

Вы также можете выбрать из более чем 17 500 голосов в нашей библиотеке голосов (Voice Library). Просто замените идентификатор примера в фрагменте кода на тот, который вам больше нравится.

Типичные сценарии использования API преобразования текста в речь в приложении

Как только ваш первый запрос заработает, тот же вызов может обеспечивать работу множества функций.

Вот несколько примеров использования TTS API в приложении:

• Чтение внутри приложения: отправляйте текст частями и воспроизводите аудио по порядку. Для получения дополнительной информации ознакомьтесь с нашим руководством по интеграции пакетной обработки API.
• Ответы аудио чат-бота: пропускайте каждый ответ вашего чат-бота через API и транслируйте аудио обратно пользователю для более интерактивного взаимодействия.
• Телефонные системы: запрашивайте выходной формат ulaw_8000 для телефонии. Следуйте нашему руководству по интеграции Twilio TTS для получения дополнительной информации.

Если вы хотите создать голосовых агентов, поддерживающих двусторонний разговор, ElevenAgents создана именно для этого. Вы настраиваете и развертываете агента на платформе вместо того, чтобы самостоятельно собирать весь конвейер обработки речи. Изучите ElevenAgents, чтобы узнать больше.

Создавайте TTS API в своих приложениях с помощью ElevenAPI

Интеграция преобразования текста в речь сводится к четырем основным шагам: создание API-ключа, установка SDK, выполнение первого запроса и его запуск. Тот же вызов работает в TypeScript, Python или любом другом языке, способном выполнять HTTP-запросы. Вы также можете выбрать модель и голос, подходящие для вашего приложения.

Если вы готовы внедрить TTS в свои приложения, зарегистрируйтесь, чтобы сделать свой первый запрос с помощью ElevenAPI уже сегодня, или узнайте больше об API преобразования текста в речь.

Часто задаваемые вопросы