diff --git a/docs/uk/providers/google.md b/docs/uk/providers/google.md index 001cdab0e..87e4e475d 100644 --- a/docs/uk/providers/google.md +++ b/docs/uk/providers/google.md @@ -1,22 +1,22 @@ --- read_when: - Ви хочете використовувати моделі Google Gemini з OpenClaw - - Вам потрібен API key або потік автентифікації OAuth -summary: Налаштування Google Gemini (API key + OAuth, генерація зображень, розуміння медіа, вебпошук) + - Вам потрібен ключ API або потік автентифікації OAuth +summary: Налаштування Google Gemini (ключ API + OAuth, генерація зображень, розуміння медіа, TTS, вебпошук) title: Google (Gemini) x-i18n: - generated_at: "2026-04-12T10:03:22Z" + generated_at: "2026-04-16T06:26:12Z" model: gpt-5.4 provider: openai - source_hash: 64b848add89061b208a5d6b19d206c433cace5216a0ca4b63d56496aecbde452 + source_hash: ec2d62855f5e80efda758aad71bcaa95c38b1e41761fa1100d47a06c62881419 source_path: providers/google.md workflow: 15 --- # Google (Gemini) -Plugin Google надає доступ до моделей Gemini через Google AI Studio, а також -генерацію зображень, розуміння медіа (зображення/аудіо/відео) і вебпошук через +Плагін Google надає доступ до моделей Gemini через Google AI Studio, а також до +генерації зображень, розуміння медіа (зображення/аудіо/відео), перетворення тексту на мовлення та вебпошуку через Gemini Grounding. - Провайдер: `google` @@ -26,14 +26,14 @@ Gemini Grounding. ## Початок роботи -Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування. +Оберіть бажаний спосіб автентифікації та виконайте кроки налаштування. - **Найкраще підходить для:** стандартного доступу до Gemini API через Google AI Studio. + **Найкраще для:** стандартного доступу до Gemini API через Google AI Studio. - + ```bash openclaw onboard --auth-choice gemini-api-key ``` @@ -47,7 +47,7 @@ Gemini Grounding. --gemini-api-key "$GEMINI_API_KEY" ``` - + ```json5 { agents: { @@ -58,7 +58,7 @@ Gemini Grounding. } ``` - + ```bash openclaw models list --provider google ``` @@ -66,21 +66,21 @@ Gemini Grounding. - Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` обидві підтримуються. Використовуйте ту, яка у вас уже налаштована. + Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` обидві підтримуються. Використовуйте ту, яку вже налаштовано у вас. - **Найкраще підходить для:** повторного використання наявного входу Gemini CLI через PKCE OAuth замість окремого API key. + **Найкраще для:** повторного використання наявного входу Gemini CLI через PKCE OAuth замість окремого ключа API. Провайдер `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі - повідомляють про обмеження акаунта при використанні OAuth у такий спосіб. Використовуйте на власний ризик. + повідомляють про обмеження облікового запису під час використання OAuth у такий спосіб. Використовуйте на власний ризик. - + Локальна команда `gemini` має бути доступною в `PATH`. ```bash @@ -92,14 +92,14 @@ Gemini Grounding. ``` OpenClaw підтримує як встановлення через Homebrew, так і глобальні встановлення npm, зокрема - типові Windows/npm-розкладки. + поширені схеми Windows/npm. - + ```bash openclaw models auth login --provider google-gemini-cli --set-default ``` - + ```bash openclaw models list --provider google-gemini-cli ``` @@ -107,7 +107,7 @@ Gemini Grounding. - Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview` - - Аліас: `gemini-cli` + - Псевдонім: `gemini-cli` **Змінні середовища:** @@ -117,39 +117,41 @@ Gemini Grounding. (Або варіанти `GEMINI_CLI_*`.) - Якщо OAuth-запити Gemini CLI не вдаються після входу, установіть `GOOGLE_CLOUD_PROJECT` або + Якщо запити Gemini CLI OAuth не вдаються після входу, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway і повторіть спробу. - Якщо вхід не вдається до запуску потоку в браузері, переконайтеся, що локальна команда `gemini` - установлена й доступна в `PATH`. + Якщо вхід не вдається до початку потоку в браузері, переконайтеся, що локальну команду `gemini` + встановлено та додано до `PATH`. - Провайдер `google-gemini-cli`, що підтримує лише OAuth, є окремою - поверхнею текстового інференсу. Генерація зображень, розуміння медіа та Gemini Grounding залишаються на ідентифікаторі провайдера `google`. + Провайдер `google-gemini-cli`, який підтримує лише OAuth, є окремою + поверхнею текстового інференсу. Генерація зображень, розуміння медіа та Gemini Grounding залишаються на + ідентифікаторі провайдера `google`. ## Можливості -| Можливість | Підтримується | -| ----------------------- | ----------------- | -| Чат-комплішени | Так | -| Генерація зображень | Так | -| Генерація музики | Так | -| Розуміння зображень | Так | -| Транскрипція аудіо | Так | -| Розуміння відео | Так | -| Вебпошук (Grounding) | Так | -| Thinking/reasoning | Так (Gemini 3.1+) | -| Моделі Gemma 4 | Так | +| Можливість | Підтримка | +| ---------------------- | ------------------ | +| Завершення чату | Так | +| Генерація зображень | Так | +| Генерація музики | Так | +| Перетворення тексту на мовлення | Так | +| Розуміння зображень | Так | +| Транскрипція аудіо | Так | +| Розуміння відео | Так | +| Вебпошук (Grounding) | Так | +| Мислення/міркування | Так (Gemini 3.1+) | +| Моделі Gemma 4 | Так | -Моделі Gemma 4 (наприклад, `gemma-4-26b-a4b-it`) підтримують режим thinking. OpenClaw +Моделі Gemma 4 (наприклад, `gemma-4-26b-a4b-it`) підтримують режим мислення. OpenClaw перезаписує `thinkingBudget` у підтримуваний Google `thinkingLevel` для Gemma 4. -Установлення thinking у `off` зберігає вимкнений thinking замість зіставлення з +Встановлення мислення в `off` зберігає вимкнений стан мислення замість зіставлення з `MINIMAL`. @@ -163,7 +165,7 @@ Gemini Grounding. - Режим редагування: увімкнено, до 5 вхідних зображень - Керування геометрією: `size`, `aspectRatio` і `resolution` -Щоб використовувати Google як провайдер зображень за замовчуванням: +Щоб використовувати Google як провайдера зображень за замовчуванням: ```json5 { @@ -178,20 +180,20 @@ Gemini Grounding. ``` -Див. [Генерація зображень](/uk/tools/image-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover. +Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку перемикання при збоях. ## Генерація відео -Вбудований Plugin `google` також реєструє генерацію відео через спільний +Вбудований плагін `google` також реєструє генерацію відео через спільний інструмент `video_generate`. - Модель відео за замовчуванням: `google/veo-3.1-fast-generate-preview` -- Режими: text-to-video, image-to-video і потоки з посиланням на одне відео +- Режими: text-to-video, image-to-video та потоки з одним опорним відео - Підтримує `aspectRatio`, `resolution` і `audio` - Поточне обмеження тривалості: **від 4 до 8 секунд** -Щоб використовувати Google як провайдер відео за замовчуванням: +Щоб використовувати Google як провайдера відео за замовчуванням: ```json5 { @@ -206,22 +208,22 @@ Gemini Grounding. ``` -Див. [Генерація відео](/uk/tools/video-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover. +Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку перемикання при збоях. ## Генерація музики -Вбудований Plugin `google` також реєструє генерацію музики через спільний +Вбудований плагін `google` також реєструє генерацію музики через спільний інструмент `music_generate`. - Модель музики за замовчуванням: `google/lyria-3-clip-preview` - Також підтримує `google/lyria-3-pro-preview` - Керування запитом: `lyrics` і `instrumental` - Формат виводу: `mp3` за замовчуванням, а також `wav` у `google/lyria-3-pro-preview` -- Вхідні дані-посилання: до 10 зображень -- Запуски з підтримкою сесій відокремлюються через спільний потік task/status, включно з `action: "status"` +- Опорні вхідні дані: до 10 зображень +- Запуски з підтримкою сесій відокремлюються через спільний потік задачі/статусу, зокрема `action: "status"` -Щоб використовувати Google як провайдер музики за замовчуванням: +Щоб використовувати Google як провайдера музики за замовчуванням: ```json5 { @@ -236,22 +238,66 @@ Gemini Grounding. ``` -Див. [Генерація музики](/uk/tools/music-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки failover. +Див. [Генерація музики](/uk/tools/music-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку перемикання при збоях. + + +## Перетворення тексту на мовлення + +Вбудований мовленнєвий провайдер `google` використовує шлях Gemini API TTS з +`gemini-3.1-flash-tts-preview`. + +- Голос за замовчуванням: `Kore` +- Автентифікація: `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` +- Вивід: WAV для звичайних TTS-вкладень, PCM для Talk/телефонії +- Нативний вивід голосових нотаток: не підтримується в цьому шляху Gemini API, оскільки API повертає PCM, а не Opus + +Щоб використовувати Google як TTS-провайдера за замовчуванням: + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "google", + providers: { + google: { + model: "gemini-3.1-flash-tts-preview", + voiceName: "Kore", + }, + }, + }, + }, +} +``` + +Gemini API TTS приймає виразні квадратні аудіотеги в тексті, наприклад +`[whispers]` або `[laughs]`. Щоб приховати теги з видимої відповіді в чаті, але +надсилати їх до TTS, помістіть їх у блок `[[tts:text]]...[[/tts:text]]`: + +```text +Ось чистий текст відповіді. + +[[tts:text]][whispers] Ось озвучена версія.[[/tts:text]] +``` + + +Ключ API Google Cloud Console, обмежений Gemini API, є дійсним для цього +провайдера. Це не окремий шлях Cloud Text-to-Speech API. ## Розширене налаштування - - Для прямих запусків Gemini API (`api: "google-generative-ai"`), OpenClaw - передає налаштований дескриптор `cachedContent` у запити до Gemini. + + Для прямих запусків Gemini API (`api: "google-generative-ai"`) OpenClaw + передає налаштований дескриптор `cachedContent` у запити Gemini. - - Налаштовуйте параметри для окремої моделі або глобальні параметри через - `cachedContent` або застарілий `cached_content` - - Якщо присутні обидва, перевага надається `cachedContent` + - Налаштовуйте параметри для окремої моделі або глобально за допомогою + `cachedContent` або застарілого `cached_content` + - Якщо присутні обидва, `cachedContent` має пріоритет - Приклад значення: `cachedContents/prebuilt-context` - - Використання Gemini cache-hit нормалізується в OpenClaw `cacheRead` із - висхідного `cachedContentTokenCount` + - Використання влучення кешу Gemini нормалізується в OpenClaw `cacheRead` з + вихідного `cachedContentTokenCount` ```json5 { @@ -271,19 +317,19 @@ Gemini Grounding. - - Під час використання OAuth-провайдера `google-gemini-cli`, OpenClaw нормалізує + + Під час використання OAuth-провайдера `google-gemini-cli` OpenClaw нормалізує JSON-вивід CLI таким чином: - Текст відповіді береться з поля CLI JSON `response`. - - Використання повертається до `stats`, коли CLI залишає `usage` порожнім. + - Використання повертається до `stats`, якщо CLI залишає `usage` порожнім. - `stats.cached` нормалізується в OpenClaw `cacheRead`. - - Якщо `stats.input` відсутній, OpenClaw обчислює вхідні токени з + - Якщо `stats.input` відсутній, OpenClaw виводить кількість вхідних токенів із `stats.input_tokens - stats.cached`. - + Якщо Gateway працює як демон (launchd/systemd), переконайтеся, що `GEMINI_API_KEY` доступний цьому процесу (наприклад, у `~/.openclaw/.env` або через `env.shellEnv`). @@ -293,16 +339,16 @@ Gemini Grounding. ## Пов’язане - - Вибір провайдерів, посилань на моделі та поведінки failover. + + Вибір провайдерів, посилань на моделі та поведінки перемикання при збоях. - + Спільні параметри інструмента зображень і вибір провайдера. - + Спільні параметри інструмента відео і вибір провайдера. - + Спільні параметри інструмента музики і вибір провайдера. diff --git a/docs/uk/tools/tts.md b/docs/uk/tools/tts.md index 9ff6a9578..d4637d9fd 100644 --- a/docs/uk/tools/tts.md +++ b/docs/uk/tools/tts.md @@ -1,80 +1,82 @@ --- read_when: - - Увімкнення синтезу мовлення для відповідей + - Увімкнення перетворення тексту на мовлення для відповідей - Налаштування провайдерів TTS або обмежень - - Використання команд /tts -summary: Синтез мовлення (TTS) для вихідних відповідей -title: Синтез мовлення + - Використання команд `/tts` +summary: Перетворення тексту на мовлення (TTS) для вихідних відповідей +title: Text-to-Speech x-i18n: - generated_at: "2026-04-12T22:42:43Z" + generated_at: "2026-04-16T06:26:13Z" model: gpt-5.4 provider: openai - source_hash: ad79a6be34879347dc73fdab1bd219823cd7c6aa8504e3e4c73e1a0554c837c5 + source_hash: de7c1dc8831c1ba307596afd48cb4d36f844724887a13b17e35f41ef5174a86f source_path: tools/tts.md workflow: 15 --- -# Синтез мовлення (TTS) +# Перетворення тексту на мовлення (TTS) -OpenClaw може перетворювати вихідні відповіді на аудіо за допомогою ElevenLabs, Microsoft, MiniMax або OpenAI. +OpenClaw може перетворювати вихідні відповіді на аудіо за допомогою ElevenLabs, Google Gemini, Microsoft, MiniMax або OpenAI. Це працює всюди, де OpenClaw може надсилати аудіо. ## Підтримувані сервіси - **ElevenLabs** (основний або резервний провайдер) +- **Google Gemini** (основний або резервний провайдер; використовує Gemini API TTS) - **Microsoft** (основний або резервний провайдер; поточна вбудована реалізація використовує `node-edge-tts`) - **MiniMax** (основний або резервний провайдер; використовує API T2A v2) -- **OpenAI** (основний або резервний провайдер; також використовується для зведень) +- **OpenAI** (основний або резервний провайдер; також використовується для підсумків) -### Примітки щодо Microsoft speech +### Примітки щодо мовлення Microsoft -Вбудований провайдер Microsoft speech наразі використовує онлайн-сервіс +Вбудований провайдер мовлення Microsoft наразі використовує онлайн-сервіс нейронного TTS Microsoft Edge через бібліотеку `node-edge-tts`. Це хостований сервіс (не локальний), він використовує кінцеві точки Microsoft і не потребує API-ключа. -`node-edge-tts` надає параметри налаштування мовлення та вихідні формати, але -сервіс підтримує не всі параметри. Застаріла конфігурація та вхідні дані директив -із `edge` усе ще працюють і нормалізуються до `microsoft`. +`node-edge-tts` надає параметри конфігурації мовлення та вихідні формати, але +не всі параметри підтримуються сервісом. Застаріла конфігурація та введення директив +із використанням `edge` усе ще працюють і нормалізуються до `microsoft`. Оскільки цей шлях використовує публічний вебсервіс без опублікованих SLA або квот, -вважайте його best-effort. Якщо вам потрібні гарантовані ліміти та підтримка, використовуйте OpenAI +вважайте його рішенням із найкращими можливими зусиллями. Якщо вам потрібні гарантовані ліміти та підтримка, використовуйте OpenAI або ElevenLabs. ## Необов’язкові ключі -Якщо ви хочете використовувати OpenAI, ElevenLabs або MiniMax: +Якщо ви хочете використовувати OpenAI, ElevenLabs, Google Gemini або MiniMax: - `ELEVENLABS_API_KEY` (або `XI_API_KEY`) +- `GEMINI_API_KEY` (або `GOOGLE_API_KEY`) - `MINIMAX_API_KEY` - `OPENAI_API_KEY` -Microsoft speech **не** потребує API-ключа. +Мовлення Microsoft **не** потребує API-ключа. -Якщо налаштовано кілька провайдерів, спочатку використовується вибраний провайдер, а інші слугують резервними варіантами. -Автоматичне зведення використовує налаштовану `summaryModel` (або `agents.defaults.model.primary`), -тому цей провайдер також має бути автентифікований, якщо ви вмикаєте зведення. +Якщо налаштовано кілька провайдерів, спочатку використовується вибраний провайдер, а інші стають резервними варіантами. +Автоматичне створення підсумків використовує налаштований `summaryModel` (або `agents.defaults.model.primary`), +тому якщо ви вмикаєте підсумки, цей провайдер також має бути автентифікований. ## Посилання на сервіси -- [Посібник з OpenAI Text-to-Speech](https://platform.openai.com/docs/guides/text-to-speech) -- [Довідник API OpenAI Audio](https://platform.openai.com/docs/api-reference/audio) +- [Посібник OpenAI Text-to-Speech](https://platform.openai.com/docs/guides/text-to-speech) +- [Довідка API Audio OpenAI](https://platform.openai.com/docs/api-reference/audio) - [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech) - [Автентифікація ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication) -- [API MiniMax T2A v2](https://platform.minimaxi.com/document/T2A%20V2) +- [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2) - [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) - [Вихідні формати Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) ## Чи ввімкнено це за замовчуванням? Ні. Автоматичний TTS **вимкнено** за замовчуванням. Увімкніть його в конфігурації через -`messages.tts.auto` або локально через `/tts on`. +`messages.tts.auto` або локально за допомогою `/tts on`. -Коли `messages.tts.provider` не задано, OpenClaw вибирає перший налаштований -провайдер мовлення в порядку автоматичного вибору реєстру. +Коли `messages.tts.provider` не задано, OpenClaw вибирає першого +налаштованого провайдера мовлення в порядку автоматичного вибору реєстру. ## Конфігурація -Конфігурація TTS розташована в `messages.tts` у `openclaw.json`. -Повну схему наведено в [Конфігурація Gateway](/uk/gateway/configuration). +Конфігурація TTS розміщується в `messages.tts` у `openclaw.json`. +Повна схема наведена в [Конфігурація Gateway](/uk/gateway/configuration). ### Мінімальна конфігурація (увімкнення + провайдер) @@ -177,7 +179,33 @@ Microsoft speech **не** потребує API-ключа. } ``` -### Вимкнути Microsoft speech +### Google Gemini як основний + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "google", + providers: { + google: { + apiKey: "gemini_api_key", + model: "gemini-3.1-flash-tts-preview", + voiceName: "Kore", + }, + }, + }, + }, +} +``` + +Google Gemini TTS використовує шлях API-ключа Gemini. API-ключ Google Cloud Console, +обмежений Gemini API, тут є дійсним, і це той самий тип ключа, який використовується +вбудованим провайдером генерації зображень Google. Порядок визначення: +`messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> +`GEMINI_API_KEY` -> `GOOGLE_API_KEY`. + +### Вимкнення мовлення Microsoft ```json5 { @@ -208,7 +236,7 @@ Microsoft speech **не** потребує API-ключа. } ``` -### Відповідати аудіо лише після вхідного голосового повідомлення +### Відповідати лише аудіо після вхідного голосового повідомлення ```json5 { @@ -220,7 +248,7 @@ Microsoft speech **не** потребує API-ключа. } ``` -### Вимкнути автоматичне зведення для довгих відповідей +### Вимкнення автоматичного підсумку для довгих відповідей ```json5 { @@ -243,83 +271,87 @@ Microsoft speech **не** потребує API-ключа. - `auto`: режим автоматичного TTS (`off`, `always`, `inbound`, `tagged`). - `inbound` надсилає аудіо лише після вхідного голосового повідомлення. - `tagged` надсилає аудіо лише тоді, коли відповідь містить директиви `[[tts:key=value]]` або блок `[[tts:text]]...[[/tts:text]]`. -- `enabled`: застарілий перемикач (doctor переносить це до `auto`). +- `enabled`: застарілий перемикач (doctor мігрує його до `auto`). - `mode`: `"final"` (типово) або `"all"` (включає відповіді інструментів/блоків). -- `provider`: ідентифікатор провайдера мовлення, наприклад `"elevenlabs"`, `"microsoft"`, `"minimax"` або `"openai"` (резервний вибір відбувається автоматично). -- Якщо `provider` **не задано**, OpenClaw використовує перший налаштований провайдер мовлення в порядку автоматичного вибору реєстру. -- Застарілий `provider: "edge"` усе ще працює і нормалізується до `microsoft`. -- `summaryModel`: необов’язкова недорога модель для автоматичного зведення; типово `agents.defaults.model.primary`. - - Приймає `provider/model` або псевдонім налаштованої моделі. -- `modelOverrides`: дозволяє моделі виводити директиви TTS (увімкнено за замовчуванням). +- `provider`: ідентифікатор провайдера мовлення, наприклад `"elevenlabs"`, `"google"`, `"microsoft"`, `"minimax"` або `"openai"` (резервне перемикання відбувається автоматично). +- Якщо `provider` **не задано**, OpenClaw використовує першого налаштованого провайдера мовлення в порядку автоматичного вибору реєстру. +- Застарілий `provider: "edge"` усе ще працює та нормалізується до `microsoft`. +- `summaryModel`: необов’язкова недорога модель для автоматичного підсумку; типово використовується `agents.defaults.model.primary`. + - Приймає `provider/model` або налаштований псевдонім моделі. +- `modelOverrides`: дозволяє моделі видавати директиви TTS (типово ввімкнено). - `allowProvider` типово має значення `false` (перемикання провайдера вмикається явно). -- `providers.`: налаштування провайдера, що належать провайдеру мовлення, із ключем за його ідентифікатором. -- Застарілі прямі блоки провайдерів (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) автоматично переносяться до `messages.tts.providers.` під час завантаження. -- `maxTextLength`: жорстке обмеження для вхідного тексту TTS (символи). `/tts audio` завершується помилкою, якщо ліміт перевищено. +- `providers.`: налаштування, що належать провайдеру, із ключем за ідентифікатором провайдера мовлення. +- Застарілі прямі блоки провайдерів (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) автоматично мігруються до `messages.tts.providers.` під час завантаження. +- `maxTextLength`: жорстке обмеження для вхідного тексту TTS (символи). `/tts audio` завершується помилкою, якщо його перевищено. - `timeoutMs`: тайм-аут запиту (мс). -- `prefsPath`: перевизначає шлях до локального JSON-файла prefs (провайдер/ліміт/зведення). -- Значення `apiKey` беруться з env vars як запасний варіант (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`). -- `providers.elevenlabs.baseUrl`: перевизначає базовий URL API ElevenLabs. +- `prefsPath`: перевизначає локальний шлях до JSON-файлу prefs (провайдер/ліміт/підсумок). +- Значення `apiKey` резервно беруться зі змінних середовища (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`). +- `providers.elevenlabs.baseUrl`: перевизначає базову URL-адресу API ElevenLabs. - `providers.openai.baseUrl`: перевизначає кінцеву точку OpenAI TTS. - Порядок визначення: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - Нетипові значення трактуються як OpenAI-сумісні кінцеві точки TTS, тому приймаються власні назви моделей і голосів. + - Нетипові значення вважаються OpenAI-сумісними кінцевими точками TTS, тому приймаються власні назви моделей і голосів. - `providers.elevenlabs.voiceSettings`: - `stability`, `similarityBoost`, `style`: `0..1` - `useSpeakerBoost`: `true|false` - - `speed`: `0.5..2.0` (1.0 = звичайно) + - `speed`: `0.5..2.0` (1.0 = звичайна швидкість) - `providers.elevenlabs.applyTextNormalization`: `auto|on|off` - `providers.elevenlabs.languageCode`: 2-літерний ISO 639-1 (наприклад, `en`, `de`) -- `providers.elevenlabs.seed`: ціле число `0..4294967295` (детермінізм у межах можливого) -- `providers.minimax.baseUrl`: перевизначає базовий URL API MiniMax (типово `https://api.minimax.io`, env: `MINIMAX_API_HOST`). +- `providers.elevenlabs.seed`: ціле число `0..4294967295` (детермінованість у межах найкращих можливих зусиль) +- `providers.minimax.baseUrl`: перевизначає базову URL-адресу API MiniMax (типово `https://api.minimax.io`, env: `MINIMAX_API_HOST`). - `providers.minimax.model`: модель TTS (типово `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`). - `providers.minimax.voiceId`: ідентифікатор голосу (типово `English_expressive_narrator`, env: `MINIMAX_TTS_VOICE_ID`). - `providers.minimax.speed`: швидкість відтворення `0.5..2.0` (типово 1.0). - `providers.minimax.vol`: гучність `(0, 10]` (типово 1.0; має бути більшою за 0). -- `providers.minimax.pitch`: зсув висоти тону `-12..12` (типово 0). -- `providers.microsoft.enabled`: дозволяє використання Microsoft speech (типово `true`; без API-ключа). +- `providers.minimax.pitch`: зміщення тону `-12..12` (типово 0). +- `providers.google.model`: модель Gemini TTS (типово `gemini-3.1-flash-tts-preview`). +- `providers.google.voiceName`: назва вбудованого голосу Gemini (типово `Kore`; також приймається `voice`). +- `providers.google.baseUrl`: перевизначає базову URL-адресу Gemini API. Приймається лише `https://generativelanguage.googleapis.com`. + - Якщо `messages.tts.providers.google.apiKey` пропущено, TTS може повторно використати `models.providers.google.apiKey` перед резервним переходом до env. +- `providers.microsoft.enabled`: дозволяє використання мовлення Microsoft (типово `true`; без API-ключа). - `providers.microsoft.voice`: назва нейронного голосу Microsoft (наприклад, `en-US-MichelleNeural`). - `providers.microsoft.lang`: код мови (наприклад, `en-US`). - `providers.microsoft.outputFormat`: вихідний формат Microsoft (наприклад, `audio-24khz-48kbitrate-mono-mp3`). - - Див. вихідні формати Microsoft Speech для допустимих значень; не всі формати підтримуються вбудованим транспортом на основі Edge. -- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: рядки з відсотками (наприклад, `+10%`, `-5%`). + - Дивіться вихідні формати Microsoft Speech для допустимих значень; не всі формати підтримуються вбудованим транспортом на основі Edge. +- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: рядки у відсотках (наприклад, `+10%`, `-5%`). - `providers.microsoft.saveSubtitles`: записує JSON-субтитри поруч з аудіофайлом. -- `providers.microsoft.proxy`: URL проксі для запитів Microsoft speech. +- `providers.microsoft.proxy`: URL-адреса проксі для запитів мовлення Microsoft. - `providers.microsoft.timeoutMs`: перевизначення тайм-ауту запиту (мс). - `edge.*`: застарілий псевдонім для тих самих налаштувань Microsoft. -## Перевизначення, керовані моделлю (типово увімкнено) +## Перевизначення, керовані моделлю (типово ввімкнено) -За замовчуванням модель **може** виводити директиви TTS для однієї відповіді. +Типово модель **може** видавати директиви TTS для однієї відповіді. Коли `messages.tts.auto` має значення `tagged`, ці директиви потрібні для запуску аудіо. -Коли це ввімкнено, модель може виводити директиви `[[tts:...]]`, щоб перевизначити голос -для однієї відповіді, а також необов’язковий блок `[[tts:text]]...[[/tts:text]]`, щоб -додати виразні теги (сміх, підказки для співу тощо), які мають з’являтися +Коли це ввімкнено, модель може видавати директиви `[[tts:...]]` для перевизначення голосу +для однієї відповіді, а також необов’язковий блок `[[tts:text]]...[[/tts:text]]` для +додавання виразних тегів (сміх, підказки для співу тощо), які мають з’являтися лише в аудіо. Директиви `provider=...` ігноруються, якщо не встановлено `modelOverrides.allowProvider: true`. -Приклад payload відповіді: +Приклад корисного навантаження відповіді: ``` -Ось. +Here you go. [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]] -[[tts:text]](сміється) Прочитай пісню ще раз.[[/tts:text]] +[[tts:text]](laughs) Read the song once more.[[/tts:text]] ``` Доступні ключі директив (коли ввімкнено): -- `provider` (ідентифікатор зареєстрованого провайдера мовлення, наприклад `openai`, `elevenlabs`, `minimax` або `microsoft`; потребує `allowProvider: true`) -- `voice` (голос OpenAI) або `voiceId` (ElevenLabs / MiniMax) -- `model` (модель OpenAI TTS, ідентифікатор моделі ElevenLabs або модель MiniMax) +- `provider` (ідентифікатор зареєстрованого провайдера мовлення, наприклад `openai`, `elevenlabs`, `google`, `minimax` або `microsoft`; потребує `allowProvider: true`) +- `voice` (голос OpenAI), `voiceName` / `voice_name` / `google_voice` (голос Google) або `voiceId` (ElevenLabs / MiniMax) +- `model` (модель OpenAI TTS, ідентифікатор моделі ElevenLabs або модель MiniMax) або `google_model` (модель Google TTS) - `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost` - `vol` / `volume` (гучність MiniMax, 0-10) -- `pitch` (висота тону MiniMax, від -12 до 12) +- `pitch` (тон MiniMax, від -12 до 12) - `applyTextNormalization` (`auto|on|off`) - `languageCode` (ISO 639-1) - `seed` -Вимкнути всі перевизначення моделі: +Вимкнення всіх перевизначень моделі: ```json5 { @@ -333,7 +365,7 @@ Microsoft speech **не** потребує API-ключа. } ``` -Необов’язковий allowlist (увімкнути перемикання провайдера, зберігши можливість налаштовувати інші параметри): +Необов’язковий allowlist (увімкнення перемикання провайдера зі збереженням можливості налаштовувати інші параметри): ```json5 { @@ -349,17 +381,17 @@ Microsoft speech **не** потребує API-ключа. } ``` -## Налаштування для окремого користувача +## Налаштування для окремих користувачів -Слеш-команди записують локальні перевизначення до `prefsPath` (типово: -`~/.openclaw/settings/tts.json`, можна перевизначити через `OPENCLAW_TTS_PREFS` або +Команди зі слешем записують локальні перевизначення в `prefsPath` (типово: +`~/.openclaw/settings/tts.json`, перевизначається через `OPENCLAW_TTS_PREFS` або `messages.tts.prefsPath`). Збережені поля: - `enabled` - `provider` -- `maxLength` (поріг для зведення; типово 1500 символів) +- `maxLength` (поріг підсумку; типово 1500 символів) - `summarize` (типово `true`) Вони перевизначають `messages.tts.*` для цього хоста. @@ -367,54 +399,55 @@ Microsoft speech **не** потребує API-ключа. ## Вихідні формати (фіксовані) - **Feishu / Matrix / Telegram / WhatsApp**: голосове повідомлення Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). - - 48 кГц / 64 кбіт/с — це вдалий компроміс для голосових повідомлень. + - 48 кГц / 64 кбіт/с — це хороший компроміс для голосових повідомлень. - **Інші канали**: MP3 (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). - 44,1 кГц / 128 кбіт/с — типовий баланс для чіткості мовлення. - **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32 кГц). Формат голосових нотаток нативно не підтримується; використовуйте OpenAI або ElevenLabs, якщо вам потрібні гарантовані голосові повідомлення Opus. +- **Google Gemini**: Gemini API TTS повертає необроблений PCM 24 кГц. OpenClaw обгортає його у WAV для аудіовкладень і повертає PCM напряму для Talk/телефонії. Нативний формат голосових нотаток Opus у цьому шляху не підтримується. - **Microsoft**: використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`). - - Вбудований транспорт приймає `outputFormat`, але сервіс підтримує не всі формати. - - Значення вихідного формату відповідають вихідним форматам Microsoft Speech (зокрема Ogg/WebM Opus). + - Вбудований транспорт приймає `outputFormat`, але не всі формати доступні в сервісі. + - Значення вихідного формату відповідають вихідним форматам Microsoft Speech (включно з Ogg/WebM Opus). - Telegram `sendVoice` приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні гарантовані голосові повідомлення Opus. - Якщо налаштований вихідний формат Microsoft не спрацьовує, OpenClaw повторює спробу з MP3. -Формати виводу OpenAI/ElevenLabs є фіксованими для кожного каналу (див. вище). +Вихідні формати OpenAI/ElevenLabs фіксовані для кожного каналу (див. вище). ## Поведінка автоматичного TTS -Коли цю функцію ввімкнено, OpenClaw: +Коли ввімкнено, OpenClaw: - пропускає TTS, якщо відповідь уже містить медіа або директиву `MEDIA:`. - пропускає дуже короткі відповіді (< 10 символів). -- робить зведення довгих відповідей, якщо цю функцію ввімкнено, використовуючи `agents.defaults.model.primary` (або `summaryModel`). -- прикріплює згенероване аудіо до відповіді. +- створює підсумок довгих відповідей, якщо це ввімкнено, за допомогою `agents.defaults.model.primary` (або `summaryModel`). +- додає згенероване аудіо до відповіді. -Якщо відповідь перевищує `maxLength`, а зведення вимкнено (або немає API-ключа для -моделі зведення), аудіо +Якщо відповідь перевищує `maxLength`, а підсумок вимкнено (або немає API-ключа для +моделі підсумку), аудіо пропускається, і надсилається звичайна текстова відповідь. ## Діаграма потоку ``` -Відповідь -> TTS увімкнено? - ні -> надіслати текст - так -> є медіа / MEDIA: / коротка? - так -> надіслати текст - ні -> довжина > ліміт? - ні -> TTS -> прикріпити аудіо - так -> зведення увімкнено? - ні -> надіслати текст - так -> зробити зведення (`summaryModel` або `agents.defaults.model.primary`) - -> TTS -> прикріпити аудіо +Reply -> TTS enabled? + no -> send text + yes -> has media / MEDIA: / short? + yes -> send text + no -> length > limit? + no -> TTS -> attach audio + yes -> summary enabled? + no -> send text + yes -> summarize (summaryModel or agents.defaults.model.primary) + -> TTS -> attach audio ``` -## Використання слеш-команди +## Використання команд зі слешем Є одна команда: `/tts`. -Докладніше про ввімкнення див. у [Слеш-команди](/uk/tools/slash-commands). +Докладніше про ввімкнення див. у [Команди зі слешем](/uk/tools/slash-commands). Примітка для Discord: `/tts` — це вбудована команда Discord, тому OpenClaw реєструє -`/voice` як нативну команду. Текстова команда `/tts ...` усе ще працює. +`/voice` як нативну команду там. Текстова команда `/tts ...` усе ще працює. ``` /tts off @@ -430,22 +463,22 @@ Microsoft speech **не** потребує API-ключа. - Команди потребують авторизованого відправника (правила allowlist/owner усе ще застосовуються). - Має бути ввімкнено `commands.text` або реєстрацію нативних команд. -- Конфігурація `messages.tts.auto` приймає значення `off|always|inbound|tagged`. +- Конфігурація `messages.tts.auto` приймає `off|always|inbound|tagged`. - `/tts on` записує локальне налаштування TTS як `always`; `/tts off` записує його як `off`. - Використовуйте конфігурацію, якщо вам потрібні типові значення `inbound` або `tagged`. - `limit` і `summary` зберігаються в локальних prefs, а не в основній конфігурації. - `/tts audio` генерує одноразову аудіовідповідь (не вмикає TTS). -- `/tts status` включає видимість резервного переходу для останньої спроби: - - успішний резервний перехід: `Fallback: -> ` плюс `Attempts: ...` +- `/tts status` містить видимість резервного перемикання для останньої спроби: + - успішне резервне перемикання: `Fallback: -> ` плюс `Attempts: ...` - помилка: `Error: ...` плюс `Attempts: ...` - докладна діагностика: `Attempt details: provider:outcome(reasonCode) latency` -- Збої API OpenAI та ElevenLabs тепер включають розібрані деталі помилки провайдера та ідентифікатор запиту (коли провайдер його повертає), які відображаються в помилках/логах TTS. +- Збої API OpenAI та ElevenLabs тепер містять розібрані відомості про помилку провайдера та ідентифікатор запиту (коли його повертає провайдер), що відображається в помилках/журналах TTS. ## Інструмент агента Інструмент `tts` перетворює текст на мовлення та повертає аудіовкладення для доставки у відповіді. Коли каналом є Feishu, Matrix, Telegram або WhatsApp, -аудіо доставляється як голосове повідомлення, а не як вкладений файл. +аудіо доставляється як голосове повідомлення, а не як файлове вкладення. ## Gateway RPC