Содержание
- Что такое Gemini TTS и границы этой инструкции
- Текущая схема: модель и Interactions API
- Ключ, SDK и подготовка учебного текста
- Минимальный одноголосный Python-пример
- Аудио в SDK и сыром JSON: сохранение WAV
- Голос и стиль отдельно от произносимого текста
- Редакционный порядок диагностики и прослушивания
- Частые вопросы
Gemini TTS: озвучка текста через API и сохранение WAV
Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.
Материал редакции Зерокодера. Счёт по выдаче снят собственным прогоном 8 октября 2026 года; цитаты источников приведены дословно. Обновлено: октябрь 2026.
Gemini TTS — это генерация речи из текста через Gemini API: модель принимает текстовый ввод и отдаёт аудио. В первичной документации на ai.google.dev описаны модели gemini-3.8-flash-tts и gemini-3.8-flash-lite-tts, вызов через Interactions API, настройка голоса в speech_config и сохранение WAV из base64. Ниже — пример по документации и редакционный порядок проверки. Вызов TTS не выполнялся: аудиофайл и результат прослушивания здесь не приводятся.
Собственный прогон редакции: скачали топ-10 выдачи DuckDuckGo (ru-RU) по запросу «gemini tts»: текст отдали 8 из 10. Медиана объёма читаемого текста топа — 1865 слов. Метку 2026 года несут 6 из 8 прочитанных страниц.
Что такое Gemini TTS и границы этой инструкции
TTS обозначает синтез речи из текста. В текущей официальной документации Gemini API этому посвящён раздел Speech generation: текстовый вход преобразуется в аудио. Для этой инструкции выбрана одна модель gemini-3.8-flash-tts и одноголосный запрос через Interactions API. Названия моделей из поисковых запросов сами по себе не подтверждают доступность модели: точный идентификатор сверяем с первичной страницей.
Наша задача — подготовить запрос озвучки короткого текста и понять, как сохранить возвращённое аудио. Пользовательский голосовой помощник, Gemini Live и распознавание записанной речи имеют другие сценарии. Их инструкции нельзя подставлять в этот пример без отдельной проверки интерфейса, входа и ответа. Список подсказок голосовому помощнику не объясняет устройство TTS API.
Пример рассчитан на человека, который может запустить Python и установить библиотеку. Текст и критерии проверки написаны редакцией. Мы не измеряли задержку, выразительность или произношение русского языка и не утверждаем, что пример выполнен в аккаунте. Фактический результат появляется только после успешного запроса пользователя и проверки полученного файла.
Текущая схема: модель и Interactions API
На странице Speech generation текущий одноголосный пример использует client.interactions.create. Вход input содержит пользовательский блок user_input и текстовый элемент content. Поле response_format задаёт аудио. Настройка голоса передаётся через generation_config.speech_config, а стилевое описание — в аннотации speech_metadata рядом с текстом. Эти элементы относятся к одной схеме запроса.
Для сырого REST в той же документации указан адрес https://generativelanguage.googleapis.com/v1beta/interactions. Python SDK скрывает сборку HTTP-запроса за методом клиента. Не добавляйте к нашему коду параметры из старых примеров generate_content, другого речевого API или другой библиотеки: одинаковое слово TTS в названии не подтверждает совместимость полей.
Перед запуском откройте первичную страницу и сравните модель, имя метода и структуру аргументов. Если документация изменилась, обновляйте схему целиком. Замена только имени модели не доказывает совместимость старого запроса. Запишите дату проверки и источник схемы рядом с вашим файлом, чтобы при повторном запуске понимать, откуда взяты поля.
Ключ, SDK и подготовка учебного текста
Документация Gemini API направляет за API-ключом в Google AI Studio. Выбранный проект и его доступ определяют возможность вызова. Наличие ключа не подтверждает, что любая модель доступна аккаунту. Для подготовки используйте отдельный небольшой учебный текст и проверьте настройки проекта до запуска.
Пример импортирует genai из пакета google-genai. Устанавливайте именно библиотеку для Gemini API и сверяйте её документацию с выбранным методом Interactions. Похожее название другого пакета не подтверждает поддержку этого клиента. Если метод отсутствует, сначала проверьте установленный пакет и его версию; изменение текста озвучки не исправляет несовпадение интерфейсов.
Клиент в примере создаётся без ключа в исходном файле и использует настройку окружения GEMINI_API_KEY, поддерживаемую документацией API-ключей. Не вставляйте секрет в публикацию, скриншот или журнал диагностики. Если у вас несколько проектов, установите переменную в том окружении, где запускается Python, и проверьте выбранный проект через интерфейс управления, не выводя значение ключа.
Наш исходник — короткое искусственное объявление для мастерской. Он не содержит клиентских данных и внутренних инструкций. Для реальной озвучки сначала оцените право передавать текст внешнему сервису. Подготовьте окончательную редакцию: имена, сокращения, пунктуацию и слова, которые требуют особого произношения. Изменение исходника после проверки аудио требует нового прослушивания.
Минимальный одноголосный Python-пример
Этот фрагмент следует текущей схеме первичной документации. Текст объявления и стилевое описание редакционные. Вызов здесь не исполнен, файл out.wav не создавался. Сохранение произойдёт в вашем окружении при получении предусмотренного ответа.
import base64
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.8-flash-tts",
input=[{
"type": "user_input",
"content": [{
"type": "text",
"text": "Welcome to the workshop. Please sign in before using the equipment.",
"annotations": [{
"type": "speech_metadata",
"style": "calm and clear"
}]
}]
}],
response_format={"type": "audio"},
generation_config={
"speech_config": [{"voice": "Kore"}]
}
)
if interaction.output_audio is None:
raise RuntimeError("The response contains no audio output")
with open("out.wav", "wb") as audio_file:
audio_file.write(base64.b64decode(interaction.output_audio.data))
Сначала прочитайте код без запуска. Найдите место, где задаются текст, стиль, голос, модель и путь файла. Меняйте один элемент за попытку, если хотите выяснить причину изменения. Одинаковый текст сам по себе не гарантирует одинаковые байты при повторных генерациях, поэтому сравнивать следует полученные записи и условия запросов.
Защитная проверка отсутствующего аудио относится к этому учебному коду. Она помогает не обращаться к data при отсутствии output_audio; успешную авторизацию или качество речи такая проверка не подтверждает. Обработку сетевых исключений и правила повторных попыток добавляйте отдельно по потребностям своего приложения, сохраняя сообщение об ошибке без секретов.
Аудио в SDK и сыром JSON: сохранение WAV
Первичная документация различает удобное поле SDK и сырой ответ REST. В Python используется interaction.output_audio.data. В сыром JSON аудио находится в элементах steps[].content[], а поле data содержит base64. Не ищите в JSON автоматически поле output_audio: имя удобного свойства SDK не обязано быть ключом ответа HTTP.
Для выбранной схемы документация указывает WAV как формат по умолчанию. После декодирования base64 это готовые байты WAV. Не добавляйте к ним второй WAV-заголовок и не применяйте схему упаковки необработанного PCM из другого примера. Частоту дискретизации и разрядность не назначайте по памяти: сначала установите фактический формат возвращённого содержимого и требования своего проигрывателя.
При разборе REST сначала найдите элемент аудио, проверьте его тип и MIME в реальном ответе, затем декодируйте его data. Текстовый элемент или целый JSON-объект нельзя записывать как аудиофайл. Расширение .wav в имени не делает произвольные данные корректным WAV. Если нужен другой контейнер или кодек, изучите документированные параметры выбранной схемы и проверяйте полученный MIME заново.
После записи отметьте путь и размер файла, откройте его в подходящем проигрывателе и проверьте начало и конец. Отсутствие звука может иметь несколько причин; по одному признаку нельзя установить, сломан ли ответ API, декодирование или воспроизведение. Сохранённый HTTP-статус, тип содержимого и сведения о файле помогут разделить эти этапы.
Голос и стиль отдельно от произносимого текста
В текущем примере голос Kore указан в speech_config. Выбор другого голоса делайте по актуальному списку первичной страницы. Стиль calm and clear передан как аннотация speech_metadata. Эта аннотация задаёт требование к подаче, но её соблюдение всё равно оценивают на полученном аудио.
Сам текст объявления оставляйте в поле text. Если вставить туда служебную просьбу о голосе вместе с репликой, граница между содержимым и инструкцией станет неочевидной. Для выбранной схемы используйте отдельную аннотацию и проверяйте, не прозвучали ли служебные слова. В нашей статье нет примера полученной записи, поэтому это план проверки, который выполняется после вашего запроса.
Для проверки стиля можно подготовить два варианта с одним исходником и разными аннотациями. Запишите требования заранее: например, различимы ли слова, достаточны ли паузы, подходит ли подача назначению записи. Оценка «нравится больше» без этих требований не объясняет выбор для продукта. Не меняйте одновременно текст и голос, если хотите сравнить именно подачу.
При адаптации текста для другого языка составьте список имён и сокращений. Прослушайте их отдельно в контексте фразы. Полный файл может открываться успешно и содержать неверно произнесённое название. Если обнаружено расхождение, уточните исходник или поддерживаемую настройку и проверьте новую запись с начала: локальное исправление не освобождает от общей приёмки.
Редакционный порядок диагностики и прослушивания
Разделите проверку на этапы. До запроса проверьте окружение, пакет, проект, актуальную схему и право передавать текст. После запроса сохраните статус и безопасное описание ошибки. При успешном ответе проверьте наличие аудио, декодирование, контейнер, воспроизведение и содержание речи. Такое разделение задаёт порядок работы; оно не обещает, что повторная попытка устранит любую ошибку.
Если ошибка указывает на авторизацию, исследуйте настройку ключа и проекта. Если упомянуты поле запроса или модель, сравните сообщение с текущим примером первичной документации. При ограничении аккаунта руководствуйтесь фактическим сообщением сервиса и доступными настройками. Не переносите чужую числовую квоту на свой проект и не трактуйте любой отказ как нехватку денег.
Для аудио заведите журнал с полями: версия исходника, модель, голос, стиль, время запроса, результат сохранения, замечания слушателя. Поля о результате заполняются только после выполнения. Пока запрос не отправлен, пишите «не выполнялся». Это особенно важно при передаче инструкции коллеге: подготовленный код и проведённый тест имеют разные доказательства.
Для объявления из примера проверьте два смысловых элемента: приветствие мастерской и просьбу зарегистрироваться до использования оборудования. Послушайте запись целиком, затем отдельно начало и переход между предложениями. Сверьте, нет ли пропуска, добавленной реплики или обрезанного конца. При публикации добавьте проверку уровня громкости и пригодности файла для конкретной площадки по её требованиям.
Итог приёмки формулируйте по наблюдению: файл получен или нет, открывается или нет, замечание найдено или нет. Не записывайте «идеальная озвучка» без критериев и не выдавайте наш учебный сценарий за проверенное качество модели. Для автоматической публикации аудио потребуется собственная процедура контроля; эта статья объясняет один запрос и ручную проверку.
Частые вопросы
Какую модель использует этот пример?
Текущая первичная страница Speech generation документирует gemini-3.8-flash-tts с Interactions API. Именно этот идентификатор использован в коде. Кэшированные названия поисковых запросов не подтверждают наличие других моделей.
Нужен ли API-ключ?
Для этого вызова подготовьте ключ Gemini API и доступ соответствующего проекта. Документация направляет к Google AI Studio; клиент поддерживает настройку ключа через окружение. Не публикуйте секрет.
Где находятся данные аудио?
В показанном Python SDK используется interaction.output_audio.data. В сыром REST JSON аудио ищут среди steps[].content[]. Данные base64 декодируют перед записью файла.
Нужно ли создавать WAV-заголовок вручную?
В выбранной схеме ответ по умолчанию содержит готовый WAV. После декодирования его записывают как файл. Упаковка PCM из другой схемы не относится к этому примеру.
Редакция слушала результат этого кода?
Нет. Вызов TTS не выполнялся, файл не создавался. Запрос и порядок приёмки подготовлены по документации; практический результат проверяется в вашем окружении.