# Озвучка текста (TTS): как использовать

> Гайд по /v1/audio/speech — голоса и их маппинг на Gemini, форматы mp3/wav/pcm, параметры speed и instructions, бинарный ответ.

Веб-версия: https://ai.trackly.one/developers/docs/audio · Индекс документации: https://ai.trackly.one/llms.txt

`POST /v1/audio/speech` превращает текст до 4096 символов в звук и
возвращает бинарное аудио-тело — mp3, wav или pcm, не JSON. Модель —
`google/gemini-2.5-flash-preview-tts`; голос задаётся привычными
OpenAI-именами (alloy, coral, echo, nova, onyx, shimmer) или родными
именами Gemini. Списание — после успешного ответа, по фактическому расходу.

## Как озвучить текст?

**POST /v1/audio/speech**

```bash
curl https://api.trackly.one/v1/audio/speech \
  -H "Authorization: Bearer $TRACKLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash-preview-tts",
    "voice": "coral",
    "input": "Привет! Это тестовая озвучка текста."
  }' \
  --output speech.mp3
```

```python
with client.audio.speech.with_streaming_response.create(
    model="google/gemini-2.5-flash-preview-tts",
    voice="coral",
    input="Привет! Это тестовая озвучка текста.",
) as response:
    response.stream_to_file("speech.mp3")
```

```javascript
import fs from "node:fs";

const speech = await client.audio.speech.create({
  model: "google/gemini-2.5-flash-preview-tts",
  voice: "coral",
  input: "Привет! Это тестовая озвучка текста.",
});
fs.writeFileSync("speech.mp3", Buffer.from(await speech.arrayBuffer()));
```

Тело ответа — сразу байты аудио, заголовок `Content-Type` соответствует
формату (`audio/mpeg`, `audio/wav` или `audio/pcm`). Все поля запроса — в
[референсе audio/speech](https://ai.trackly.one/developers/docs/reference/audio-speech).

## Какие голоса доступны?

OpenAI-имена маппятся на голоса Gemini:

| OpenAI-имя | Голос Gemini |
| --- | --- |
| `alloy` | Puck |
| `coral` | Kore |
| `echo` | Charon |
| `nova` | Aoede |
| `onyx` | Fenrir |
| `shimmer` | Leda |

Родные имена Gemini (Puck, Kore, Charon и другие) тоже принимаются — можно
передать их прямо в `voice`. Неизвестное или пустое имя не роняет запрос:
подставится дефолтный голос Kore.

## Какие форматы аудио есть?

`response_format`: `mp3` (по умолчанию), `wav`, `pcm`. Для веба и
мессенджеров хватает mp3; wav и pcm пригодятся, если аудио пойдёт дальше в
обработку — например, в собственный пайплайн монтажа.

## Работают ли speed и instructions?

Работают, с оговоркой:

- `speed` (0.25-4.0) — у Gemini нет прямого параметра скорости, поэтому
  значение передаётся модели голосовой инструкцией «говори
  быстрее/медленнее». Результат приблизительный, не жёсткий множитель.
- `instructions` — дополнительное указание тону и подаче («читай как
  диктор новостей»). Дефолтная инструкция уже встроена (без неё Gemini TTS
  отвечает текстом вместо озвучки), ваша строка её дополняет, а не заменяет.

## Сколько стоит озвучка?

Списание — по фактическому usage провайдера, как у текстовых моделей; если
провайдер usage не вернул, расход оценивается по длине входного текста.
Тариф модели — на странице [цен для разработчиков](https://ai.trackly.one/developers/pricing),
ошибки и лимиты — в гайде [«Ошибки API»](https://ai.trackly.one/developers/docs/errors).
Послушать голоса без кода можно в
[озвучке на сайте](https://ai.trackly.one/chat/voiceover).