Gemini 3.1 Flash TTS API

Озвучивает текст естественной речью одним голосом или как диалог двух собеседников с разными голосами. Цена - 0,008 ₽ за символ текста.

Нейросеть

Gemini 3.1 Flash TTS API — Братуха.ру

Gemini 3.1 Flash TTS API

Нейросеть

API документация

Общая документация Public API · API-ключ можно создать в настройках аккаунта

Gemini 3.1 Flash TTS API

Gemini 3.1 Flash TTS озвучивает текст на русском и ещё 23 языках, а если текст смешанный, язык можно не указывать - модель определит его сама. Её используют для закадрового голоса к роликам и презентациям, озвучки уроков и инструкций, рекламных объявлений, аудиоверсий статей и коротких диалогов для подкастов и сценок.

Модель работает в двух режимах: весь текст читает один голос или два собеседника разыгрывают диалог разными голосами в одном файле. На выбор 30 готовых голосов. Манеру речи - тон, эмоцию, темп, акцент - можно описать словами, а вздох, смех, шёпот или паузу поставить прямо в тексте метками в квадратных скобках. Каждый вызов создаёт асинхронную операцию: вы получаете id, а готовый MP3 забираете отдельным запросом статуса.

Создание операции

Endpoint: POST /api/v1/operations
Авторизация: Authorization: Bearer brth_...
Запрос создаёт операцию и сразу возвращает id и стартовый статус queued.
Выполнение асинхронное. Короткий текст обычно готов за 10-20 секунд, текст на 2000-2500 символов - примерно за полторы-две с половиной минуты.

Режимы задаются полем generation_type:

single - один голос читает весь текст;
dialogue - диалог двух собеседников, у каждого свой голос.

Тело запроса

{
  "tool": "gemini-3-1-flash-tts",
  "input": {
    "...": "..."
  }
}

tool - slug нейросети, здесь всегда "gemini-3-1-flash-tts".
input - параметры конкретного запуска.
Все поля передаются напрямую внутри input, без дополнительного вложенного объекта input.

Параметры

Параметр	Тип	Обязательный	Описание
`generation_type`	`enum`	Нет	Режим: `single` (один голос) или `dialogue` (диалог двух собеседников). Если не передать, используется `single`.
`text`	`string`	Да	Текст для озвучки, от 1 до 2500 символов. В режиме `dialogue` каждая реплика начинается с имени собеседника и двоеточия, например `Анна: Привет!`. Реплики разделяйте переносом строки. В текст можно вставлять метки подачи: `[sigh]` - вздох, `[laughing]` - смех, `[whispering]` - шёпот, `[short pause]` - короткая пауза. Метки не озвучиваются.
`language`	`enum`	Нет	Язык текста, от него зависит произношение. Если не передать, используется `Russian (Russia)`. `auto` - модель определит язык сама, это удобно для текстов на нескольких языках. Остальные варианты: `Russian (Russia)` (русский), `English (United States)` (английский (США)), `English (India)` (английский (Индия)), `Arabic (Egypt)` (арабский (Египет)), `Bangla (Bangladesh)` (бенгальский), `Vietnamese (Vietnam)` (вьетнамский), `Indonesian (Indonesia)` (индонезийский), `Spanish (Spain)` (испанский), `Italian (Italy)` (итальянский), `Korean (South Korea)` (корейский), `Marathi (India)` (маратхи), `German (Germany)` (немецкий), `Dutch (Netherlands)` (нидерландский), `Polish (Poland)` (польский), `Portuguese (Brazil)` (португальский (Бразилия)), `Romanian (Romania)` (румынский), `Thai (Thailand)` (тайский), `Tamil (India)` (тамильский), `Telugu (India)` (телугу), `Turkish (Turkey)` (турецкий), `Ukrainian (Ukraine)` (украинский), `French (France)` (французский), `Hindi (India)` (хинди), `Japanese (Japan)` (японский).
`voice`	`enum`	Нет	Голос для режима `single`. Если не передать, используется `Kore`. Список голосов - ниже.
`speaker_1`	`string`	Нет	Имя первого собеседника в режиме `dialogue`: одно слово до 30 символов - буквы, цифры или `_`, без пробелов. Должно совпадать с подписью его реплик в `text`. Если не передать, используется `Анна`.
`voice_1`	`enum`	Нет	Голос первого собеседника в режиме `dialogue`. Если не передать, используется `Kore`.
`speaker_2`	`string`	Нет	Имя второго собеседника в режиме `dialogue`, по тем же правилам, что `speaker_1`, и не такое же, как у первого. Если не передать, используется `Олег`.
`voice_2`	`enum`	Нет	Голос второго собеседника в режиме `dialogue`. Если не передать, используется `Puck`.
`style_instruction`	`string`	Нет	Манера речи словами: тон, эмоция, темп, акцент. До 300 символов, работает в обоих режимах. Само указание не озвучивается. Например: `Спокойно и тепло, чуть медленнее`.
`use_advanced`	`boolean`	Нет	Включает дополнительную настройку `temperature`. Если не передать, используется `false`, и `temperature` не учитывается.
`temperature`	`number`	Нет	Вариативность подачи, от 0 до 2, работает только вместе с `"use_advanced": true`. `1` - обычная подача. Меньше - ровнее и предсказуемее, больше - живее и разнообразнее, а повторные запуски сильнее отличаются друг от друга.
`voice_gender`	`enum`	Нет	Фильтр голосов: `all` (все), `female` (женские), `male` (мужские). Если не передать, используется `all`. Если передать `female` или `male`, выбранные голоса должны быть этого пола, иначе запрос вернёт `validation_error`. Обычно поле передавать не нужно.

Голоса

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

`voice`	Голос
`Achernar`	женский
`Achird`	мужской
`Algenib`	мужской
`Algieba`	мужской
`Alnilam`	мужской
`Aoede`	женский
`Autonoe`	женский
`Callirrhoe`	женский
`Charon`	мужской
`Despina`	женский
`Enceladus`	мужской
`Erinome`	женский
`Fenrir`	мужской
`Gacrux`	женский
`Iapetus`	мужской
`Kore`	женский
`Laomedeia`	женский
`Leda`	женский
`Orus`	мужской
`Puck`	мужской
`Pulcherrima`	женский
`Rasalgethi`	мужской
`Sadachbia`	мужской
`Sadaltager`	мужской
`Schedar`	мужской
`Sulafat`	женский
`Umbriel`	мужской
`Vindemiatrix`	женский
`Zephyr`	женский
`Zubenelgenubi`	мужской

Примеры запросов

Сценарий 1. Один голос

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "gemini-3-1-flash-tts",
  "input": {
    "text": "Добрый день! Сегодня расскажу, как быстро приготовить вкусный завтрак: омлет с помидорами, зеленью и сыром. Понадобится всего десять минут.",
    "language": "Russian (Russia)",
    "voice": "Kore"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'gemini-3-1-flash-tts',
    input: {
        "text": "Добрый день! Сегодня расскажу, как быстро приготовить вкусный завтрак: омлет с помидорами, зеленью и сыром. Понадобится всего десять минут.",
        "language": "Russian (Russia)",
        "voice": "Kore"
      },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'gemini-3-1-flash-tts',
        'input': {
          "text": "Добрый день! Сегодня расскажу, как быстро приготовить вкусный завтрак: омлет с помидорами, зеленью и сыром. Понадобится всего десять минут.",
          "language": "Russian (Russia)",
          "voice": "Kore"
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 2. Диалог двух собеседников

Имена в speaker_1 и speaker_2 совпадают с подписями реплик в тексте. Сами имена не озвучиваются: модель по ним понимает, какой голос читает реплику.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "gemini-3-1-flash-tts",
  "input": {
    "generation_type": "dialogue",
    "text": "Анна: Олег, привет! Ты уже слышал новости про наш проект?\nОлег: Привет, Анна! Нет, а что случилось?\nАнна: Нам одобрили грант, представляешь?\nОлег: Вот это да! Поздравляю!",
    "language": "Russian (Russia)",
    "speaker_1": "Анна",
    "voice_1": "Kore",
    "speaker_2": "Олег",
    "voice_2": "Puck"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'gemini-3-1-flash-tts',
    input: {
        "generation_type": "dialogue",
        "text": "Анна: Олег, привет! Ты уже слышал новости про наш проект?\nОлег: Привет, Анна! Нет, а что случилось?\nАнна: Нам одобрили грант, представляешь?\nОлег: Вот это да! Поздравляю!",
        "language": "Russian (Russia)",
        "speaker_1": "Анна",
        "voice_1": "Kore",
        "speaker_2": "Олег",
        "voice_2": "Puck"
      },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'gemini-3-1-flash-tts',
        'input': {
          "generation_type": "dialogue",
          "text": "Анна: Олег, привет! Ты уже слышал новости про наш проект?\nОлег: Привет, Анна! Нет, а что случилось?\nАнна: Нам одобрили грант, представляешь?\nОлег: Вот это да! Поздравляю!",
          "language": "Russian (Russia)",
          "speaker_1": "Анна",
          "voice_1": "Kore",
          "speaker_2": "Олег",
          "voice_2": "Puck"
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 3. Манера речи

Поле style_instruction подсказывает модели, как прочитать текст. Здесь рекламное объявление читается энергично, как на радио.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "gemini-3-1-flash-tts",
  "input": {
    "text": "Внимание! Только до конца недели - скидка двадцать процентов на все зимние куртки. Успейте купить подарок себе и близким!",
    "language": "Russian (Russia)",
    "voice": "Puck",
    "style_instruction": "Энергично и радостно, как ведущий на радио"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'gemini-3-1-flash-tts',
    input: {
        "text": "Внимание! Только до конца недели - скидка двадцать процентов на все зимние куртки. Успейте купить подарок себе и близким!",
        "language": "Russian (Russia)",
        "voice": "Puck",
        "style_instruction": "Энергично и радостно, как ведущий на радио"
      },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'gemini-3-1-flash-tts',
        'input': {
          "text": "Внимание! Только до конца недели - скидка двадцать процентов на все зимние куртки. Успейте купить подарок себе и близким!",
          "language": "Russian (Russia)",
          "voice": "Puck",
          "style_instruction": "Энергично и радостно, как ведущий на радио"
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 4. Метки подачи и вариативность

Метки в квадратных скобках ставят вздох, смех, шёпот или паузу ровно в нужном месте текста. temperature чуть выше обычного делает подачу живее.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "gemini-3-1-flash-tts",
  "input": {
    "text": "Знаешь, я долго не решалась тебе сказать. [sigh] Но теперь можно. [short pause] Мы переезжаем к морю! [laughing] [whispering] Только пока никому.",
    "language": "Russian (Russia)",
    "voice": "Aoede",
    "use_advanced": true,
    "temperature": 1.3
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'gemini-3-1-flash-tts',
    input: {
        "text": "Знаешь, я долго не решалась тебе сказать. [sigh] Но теперь можно. [short pause] Мы переезжаем к морю! [laughing] [whispering] Только пока никому.",
        "language": "Russian (Russia)",
        "voice": "Aoede",
        "use_advanced": true,
        "temperature": 1.3
      },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'gemini-3-1-flash-tts',
        'input': {
          "text": "Знаешь, я долго не решалась тебе сказать. [sigh] Но теперь можно. [short pause] Мы переезжаем к морю! [laughing] [whispering] Только пока никому.",
          "language": "Russian (Russia)",
          "voice": "Aoede",
          "use_advanced": true,
          "temperature": 1.3
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 5. Текст на нескольких языках

С "language": "auto" модель сама определяет язык каждой части текста и читает её с правильным произношением.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "gemini-3-1-flash-tts",
  "input": {
    "text": "Welcome to our store! А теперь то же самое по-русски: добро пожаловать в наш магазин!",
    "language": "auto",
    "voice": "Charon"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'gemini-3-1-flash-tts',
    input: {
        "text": "Welcome to our store! А теперь то же самое по-русски: добро пожаловать в наш магазин!",
        "language": "auto",
        "voice": "Charon"
      },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'gemini-3-1-flash-tts',
        'input': {
          "text": "Welcome to our store! А теперь то же самое по-русски: добро пожаловать в наш магазин!",
          "language": "auto",
          "voice": "Charon"
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Примеры ответов

Ответ после создания

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "gemini-3-1-flash-tts",
  "cost": 1.12,
  "balance_after": 498.88,
  "created_at": "2026-09-29T12:00:00Z"
}

Ответ после завершения

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "gemini-3-1-flash-tts",
  "cost": 1.12,
  "created_at": "2026-09-29T12:00:00Z",
  "completed_at": "2026-09-29T12:00:14Z",
  "result": {
    "type": "audio",
    "urls": [
      "https://storage.yandexcloud.net/bratuha.ru.files/user_files/1790255763762-speech.mp3"
    ],
    "files": [
      {
        "url": "https://storage.yandexcloud.net/bratuha.ru.files/user_files/1790255763762-speech.mp3",
        "name": "result"
      }
    ]
  },
  "error_message": null
}

Ответ с ошибкой

{
  "id": "op_uuid-123",
  "status": "failed",
  "tool": "gemini-3-1-flash-tts",
  "cost": 1.12,
  "created_at": "2026-09-29T12:00:00Z",
  "completed_at": "2026-09-29T12:00:15Z",
  "result": null,
  "error_message": "Произошла ошибка, нейросеть временно недоступна. Попробуйте повторить запрос позже."
}

Если операция завершилась с ошибкой, списанная сумма возвращается на баланс автоматически.

Проверка статуса

После создания операции сохраните id и проверяйте её статус запросом:

GET /api/v1/operations/{id}

cURL

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/op_uuid-123

JavaScript / TypeScript

const response = await fetch(
  'https://bratuha.ru/api/v1/operations/op_uuid-123',
  {
    headers: {
      Authorization: 'Bearer brth_ваш_ключ',
    },
  }
)

const data = await response.json()

Пока озвучка создаётся, status будет queued или processing. Опрашивайте статус раз в 5-10 секунд.

Формат результата

После успешного завершения result содержит один аудиофайл MP3 (моно, 24 кГц, 128 кбит/с):

type всегда равен "audio";
urls содержит одну ссылку на MP3;
files дублирует ту же ссылку с именем файла.

В режиме dialogue обе роли звучат в одном файле. Длительность зависит от длины текста и манеры речи: 140 символов русского текста в обычном темпе звучат примерно 10 секунд, 2500 символов - около двух с половиной минут.

Ценообразование

0,008 ₽ за символ текста, то есть 8 ₽ за 1000 символов. Итог округляется вверх до копейки.
Минимальная стоимость запуска - 0,01 ₽.
Примеры: 1 символ - 0,01 ₽, 100 символов - 0,80 ₽, 1000 символов - 8 ₽, 2500 символов - 20 ₽.
В цену входят только символы поля text, включая пробелы, знаки препинания, метки подачи и имена собеседников в репликах. style_instruction, speaker_1, speaker_2, голос, язык, режим и temperature на цену не влияют.
Сумма списывается при создании операции и видна в поле cost. Если операция завершилась с ошибкой, деньги возвращаются на баланс автоматически.

Ограничения и практические заметки

POST /api/v1/operations не идемпотентен: каждый повторный запрос создаёт новую операцию и списывает деньги.
Операция выполняется асинхронно: после queued проверяйте статус по id.
Текст длиннее 2500 символов, значения вне списков language и голосов, имя собеседника с пробелом или другими знаками, а также несовпадение голоса с voice_gender вернут validation_error ещё до создания операции. Длинный текст разбейте на части по абзацам и озвучьте несколькими запросами.
Указывайте в language язык, на котором написан текст: так произношение будет точнее. auto выбирайте для текстов, где встречается несколько языков.
В режиме dialogue собеседников всегда двое. Подписывайте каждую реплику ровно тем именем, которое передали в speaker_1 или speaker_2, иначе модель может перепутать голоса.
Метки подачи пишите латиницей в квадратных скобках: [sigh], [laughing], [whispering], [short pause]. Общий настрой всего текста удобнее задать в style_instruction, а метками отмечать отдельные моменты.
Модель иногда отказывает без понятной причины, чаще на длинных текстах. Если операция завершилась с ошибкой, повторите запрос или разбейте текст на части - деньги за неудачный запуск возвращаются автоматически.
Пунктуация помогает модели: запятые и точки дают паузы, восклицательный и вопросительный знаки меняют интонацию.

API документация

Общая документация Public API · API-ключ можно создать в настройках аккаунта

Gemini 3.1 Flash TTS API

Создание операции

Endpoint: POST /api/v1/operations
Авторизация: Authorization: Bearer brth_...
Запрос создаёт операцию и сразу возвращает id и стартовый статус queued.
Выполнение асинхронное. Короткий текст обычно готов за 10-20 секунд, текст на 2000-2500 символов - примерно за полторы-две с половиной минуты.

Режимы задаются полем generation_type:

single - один голос читает весь текст;
dialogue - диалог двух собеседников, у каждого свой голос.

Тело запроса

{
  "tool": "gemini-3-1-flash-tts",
  "input": {
    "...": "..."
  }
}

tool - slug нейросети, здесь всегда "gemini-3-1-flash-tts".
input - параметры конкретного запуска.
Все поля передаются напрямую внутри input, без дополнительного вложенного объекта input.

Параметры

Параметр	Тип	Обязательный	Описание
`generation_type`	`enum`	Нет	Режим: `single` (один голос) или `dialogue` (диалог двух собеседников). Если не передать, используется `single`.
`text`	`string`	Да	Текст для озвучки, от 1 до 2500 символов. В режиме `dialogue` каждая реплика начинается с имени собеседника и двоеточия, например `Анна: Привет!`. Реплики разделяйте переносом строки. В текст можно вставлять метки подачи: `[sigh]` - вздох, `[laughing]` - смех, `[whispering]` - шёпот, `[short pause]` - короткая пауза. Метки не озвучиваются.
`language`	`enum`	Нет	Язык текста, от него зависит произношение. Если не передать, используется `Russian (Russia)`. `auto` - модель определит язык сама, это удобно для текстов на нескольких языках. Остальные варианты: `Russian (Russia)` (русский), `English (United States)` (английский (США)), `English (India)` (английский (Индия)), `Arabic (Egypt)` (арабский (Египет)), `Bangla (Bangladesh)` (бенгальский), `Vietnamese (Vietnam)` (вьетнамский), `Indonesian (Indonesia)` (индонезийский), `Spanish (Spain)` (испанский), `Italian (Italy)` (итальянский), `Korean (South Korea)` (корейский), `Marathi (India)` (маратхи), `German (Germany)` (немецкий), `Dutch (Netherlands)` (нидерландский), `Polish (Poland)` (польский), `Portuguese (Brazil)` (португальский (Бразилия)), `Romanian (Romania)` (румынский), `Thai (Thailand)` (тайский), `Tamil (India)` (тамильский), `Telugu (India)` (телугу), `Turkish (Turkey)` (турецкий), `Ukrainian (Ukraine)` (украинский), `French (France)` (французский), `Hindi (India)` (хинди), `Japanese (Japan)` (японский).
`voice`	`enum`	Нет	Голос для режима `single`. Если не передать, используется `Kore`. Список голосов - ниже.
`speaker_1`	`string`	Нет	Имя первого собеседника в режиме `dialogue`: одно слово до 30 символов - буквы, цифры или `_`, без пробелов. Должно совпадать с подписью его реплик в `text`. Если не передать, используется `Анна`.
`voice_1`	`enum`	Нет	Голос первого собеседника в режиме `dialogue`. Если не передать, используется `Kore`.
`speaker_2`	`string`	Нет	Имя второго собеседника в режиме `dialogue`, по тем же правилам, что `speaker_1`, и не такое же, как у первого. Если не передать, используется `Олег`.
`voice_2`	`enum`	Нет	Голос второго собеседника в режиме `dialogue`. Если не передать, используется `Puck`.
`style_instruction`	`string`	Нет	Манера речи словами: тон, эмоция, темп, акцент. До 300 символов, работает в обоих режимах. Само указание не озвучивается. Например: `Спокойно и тепло, чуть медленнее`.
`use_advanced`	`boolean`	Нет	Включает дополнительную настройку `temperature`. Если не передать, используется `false`, и `temperature` не учитывается.
`temperature`	`number`	Нет	Вариативность подачи, от 0 до 2, работает только вместе с `"use_advanced": true`. `1` - обычная подача. Меньше - ровнее и предсказуемее, больше - живее и разнообразнее, а повторные запуски сильнее отличаются друг от друга.
`voice_gender`	`enum`	Нет	Фильтр голосов: `all` (все), `female` (женские), `male` (мужские). Если не передать, используется `all`. Если передать `female` или `male`, выбранные голоса должны быть этого пола, иначе запрос вернёт `validation_error`. Обычно поле передавать не нужно.

Голоса

`voice`	Голос
`Achernar`	женский
`Achird`	мужской
`Algenib`	мужской
`Algieba`	мужской
`Alnilam`	мужской
`Aoede`	женский
`Autonoe`	женский
`Callirrhoe`	женский
`Charon`	мужской
`Despina`	женский
`Enceladus`	мужской
`Erinome`	женский
`Fenrir`	мужской
`Gacrux`	женский
`Iapetus`	мужской
`Kore`	женский
`Laomedeia`	женский
`Leda`	женский
`Orus`	мужской
`Puck`	мужской
`Pulcherrima`	женский
`Rasalgethi`	мужской
`Sadachbia`	мужской
`Sadaltager`	мужской
`Schedar`	мужской
`Sulafat`	женский
`Umbriel`	мужской
`Vindemiatrix`	женский
`Zephyr`	женский
`Zubenelgenubi`	мужской

Примеры запросов

Сценарий 1. Один голос

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "gemini-3-1-flash-tts",
  "input": {
    "text": "Добрый день! Сегодня расскажу, как быстро приготовить вкусный завтрак: омлет с помидорами, зеленью и сыром. Понадобится всего десять минут.",
    "language": "Russian (Russia)",
    "voice": "Kore"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'gemini-3-1-flash-tts',
    input: {
        "text": "Добрый день! Сегодня расскажу, как быстро приготовить вкусный завтрак: омлет с помидорами, зеленью и сыром. Понадобится всего десять минут.",
        "language": "Russian (Russia)",
        "voice": "Kore"
      },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'gemini-3-1-flash-tts',
        'input': {
          "text": "Добрый день! Сегодня расскажу, как быстро приготовить вкусный завтрак: омлет с помидорами, зеленью и сыром. Понадобится всего десять минут.",
          "language": "Russian (Russia)",
          "voice": "Kore"
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 2. Диалог двух собеседников

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "gemini-3-1-flash-tts",
  "input": {
    "generation_type": "dialogue",
    "text": "Анна: Олег, привет! Ты уже слышал новости про наш проект?\nОлег: Привет, Анна! Нет, а что случилось?\nАнна: Нам одобрили грант, представляешь?\nОлег: Вот это да! Поздравляю!",
    "language": "Russian (Russia)",
    "speaker_1": "Анна",
    "voice_1": "Kore",
    "speaker_2": "Олег",
    "voice_2": "Puck"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'gemini-3-1-flash-tts',
    input: {
        "generation_type": "dialogue",
        "text": "Анна: Олег, привет! Ты уже слышал новости про наш проект?\nОлег: Привет, Анна! Нет, а что случилось?\nАнна: Нам одобрили грант, представляешь?\nОлег: Вот это да! Поздравляю!",
        "language": "Russian (Russia)",
        "speaker_1": "Анна",
        "voice_1": "Kore",
        "speaker_2": "Олег",
        "voice_2": "Puck"
      },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'gemini-3-1-flash-tts',
        'input': {
          "generation_type": "dialogue",
          "text": "Анна: Олег, привет! Ты уже слышал новости про наш проект?\nОлег: Привет, Анна! Нет, а что случилось?\nАнна: Нам одобрили грант, представляешь?\nОлег: Вот это да! Поздравляю!",
          "language": "Russian (Russia)",
          "speaker_1": "Анна",
          "voice_1": "Kore",
          "speaker_2": "Олег",
          "voice_2": "Puck"
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 3. Манера речи

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "gemini-3-1-flash-tts",
  "input": {
    "text": "Внимание! Только до конца недели - скидка двадцать процентов на все зимние куртки. Успейте купить подарок себе и близким!",
    "language": "Russian (Russia)",
    "voice": "Puck",
    "style_instruction": "Энергично и радостно, как ведущий на радио"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'gemini-3-1-flash-tts',
    input: {
        "text": "Внимание! Только до конца недели - скидка двадцать процентов на все зимние куртки. Успейте купить подарок себе и близким!",
        "language": "Russian (Russia)",
        "voice": "Puck",
        "style_instruction": "Энергично и радостно, как ведущий на радио"
      },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'gemini-3-1-flash-tts',
        'input': {
          "text": "Внимание! Только до конца недели - скидка двадцать процентов на все зимние куртки. Успейте купить подарок себе и близким!",
          "language": "Russian (Russia)",
          "voice": "Puck",
          "style_instruction": "Энергично и радостно, как ведущий на радио"
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 4. Метки подачи и вариативность

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "gemini-3-1-flash-tts",
  "input": {
    "text": "Знаешь, я долго не решалась тебе сказать. [sigh] Но теперь можно. [short pause] Мы переезжаем к морю! [laughing] [whispering] Только пока никому.",
    "language": "Russian (Russia)",
    "voice": "Aoede",
    "use_advanced": true,
    "temperature": 1.3
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'gemini-3-1-flash-tts',
    input: {
        "text": "Знаешь, я долго не решалась тебе сказать. [sigh] Но теперь можно. [short pause] Мы переезжаем к морю! [laughing] [whispering] Только пока никому.",
        "language": "Russian (Russia)",
        "voice": "Aoede",
        "use_advanced": true,
        "temperature": 1.3
      },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'gemini-3-1-flash-tts',
        'input': {
          "text": "Знаешь, я долго не решалась тебе сказать. [sigh] Но теперь можно. [short pause] Мы переезжаем к морю! [laughing] [whispering] Только пока никому.",
          "language": "Russian (Russia)",
          "voice": "Aoede",
          "use_advanced": true,
          "temperature": 1.3
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 5. Текст на нескольких языках

С "language": "auto" модель сама определяет язык каждой части текста и читает её с правильным произношением.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "gemini-3-1-flash-tts",
  "input": {
    "text": "Welcome to our store! А теперь то же самое по-русски: добро пожаловать в наш магазин!",
    "language": "auto",
    "voice": "Charon"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'gemini-3-1-flash-tts',
    input: {
        "text": "Welcome to our store! А теперь то же самое по-русски: добро пожаловать в наш магазин!",
        "language": "auto",
        "voice": "Charon"
      },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'gemini-3-1-flash-tts',
        'input': {
          "text": "Welcome to our store! А теперь то же самое по-русски: добро пожаловать в наш магазин!",
          "language": "auto",
          "voice": "Charon"
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Примеры ответов

Ответ после создания

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "gemini-3-1-flash-tts",
  "cost": 1.12,
  "balance_after": 498.88,
  "created_at": "2026-09-29T12:00:00Z"
}

Ответ после завершения

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "gemini-3-1-flash-tts",
  "cost": 1.12,
  "created_at": "2026-09-29T12:00:00Z",
  "completed_at": "2026-09-29T12:00:14Z",
  "result": {
    "type": "audio",
    "urls": [
      "https://storage.yandexcloud.net/bratuha.ru.files/user_files/1790255763762-speech.mp3"
    ],
    "files": [
      {
        "url": "https://storage.yandexcloud.net/bratuha.ru.files/user_files/1790255763762-speech.mp3",
        "name": "result"
      }
    ]
  },
  "error_message": null
}

Ответ с ошибкой

{
  "id": "op_uuid-123",
  "status": "failed",
  "tool": "gemini-3-1-flash-tts",
  "cost": 1.12,
  "created_at": "2026-09-29T12:00:00Z",
  "completed_at": "2026-09-29T12:00:15Z",
  "result": null,
  "error_message": "Произошла ошибка, нейросеть временно недоступна. Попробуйте повторить запрос позже."
}

Если операция завершилась с ошибкой, списанная сумма возвращается на баланс автоматически.

Проверка статуса

После создания операции сохраните id и проверяйте её статус запросом:

GET /api/v1/operations/{id}

cURL

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/op_uuid-123

JavaScript / TypeScript

const response = await fetch(
  'https://bratuha.ru/api/v1/operations/op_uuid-123',
  {
    headers: {
      Authorization: 'Bearer brth_ваш_ключ',
    },
  }
)

const data = await response.json()

Пока озвучка создаётся, status будет queued или processing. Опрашивайте статус раз в 5-10 секунд.

Формат результата

После успешного завершения result содержит один аудиофайл MP3 (моно, 24 кГц, 128 кбит/с):

type всегда равен "audio";
urls содержит одну ссылку на MP3;
files дублирует ту же ссылку с именем файла.

Ценообразование

0,008 ₽ за символ текста, то есть 8 ₽ за 1000 символов. Итог округляется вверх до копейки.
Минимальная стоимость запуска - 0,01 ₽.
Примеры: 1 символ - 0,01 ₽, 100 символов - 0,80 ₽, 1000 символов - 8 ₽, 2500 символов - 20 ₽.
В цену входят только символы поля text, включая пробелы, знаки препинания, метки подачи и имена собеседников в репликах. style_instruction, speaker_1, speaker_2, голос, язык, режим и temperature на цену не влияют.
Сумма списывается при создании операции и видна в поле cost. Если операция завершилась с ошибкой, деньги возвращаются на баланс автоматически.

Ограничения и практические заметки

POST /api/v1/operations не идемпотентен: каждый повторный запрос создаёт новую операцию и списывает деньги.
Операция выполняется асинхронно: после queued проверяйте статус по id.
Текст длиннее 2500 символов, значения вне списков language и голосов, имя собеседника с пробелом или другими знаками, а также несовпадение голоса с voice_gender вернут validation_error ещё до создания операции. Длинный текст разбейте на части по абзацам и озвучьте несколькими запросами.
Указывайте в language язык, на котором написан текст: так произношение будет точнее. auto выбирайте для текстов, где встречается несколько языков.
В режиме dialogue собеседников всегда двое. Подписывайте каждую реплику ровно тем именем, которое передали в speaker_1 или speaker_2, иначе модель может перепутать голоса.
Метки подачи пишите латиницей в квадратных скобках: [sigh], [laughing], [whispering], [short pause]. Общий настрой всего текста удобнее задать в style_instruction, а метками отмечать отдельные моменты.
Модель иногда отказывает без понятной причины, чаще на длинных текстах. Если операция завершилась с ошибкой, повторите запрос или разбейте текст на части - деньги за неудачный запуск возвращаются автоматически.
Пунктуация помогает модели: запятые и точки дают паузы, восклицательный и вопросительный знаки меняют интонацию.