> ## Documentation Index
> Fetch the complete documentation index at: https://nixai.ru/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Синтез речи (Text to Speech)

Асинхронный синтез речи из текста любой длины. Вы создаёте задачу, получаете `task_id`, опрашиваете статус и забираете готовый аудиофайл одной ссылкой.

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

## Быстрый старт

### 1. Создать задачу

```bash theme={null}
curl -X POST https://api.nixai.ru/v1/audio/speech/generations \
  -H "Authorization: Bearer $NIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eleven_v3",
    "input": "Привет! Это пример синтеза речи.",
    "voice": "CwhRBWXzGAHq8TQ4Fs17"
  }'
# → {"task_id": "3f2a1c9e-..."}
```

### 2. Забрать результат

```bash theme={null}
curl -X POST https://api.nixai.ru/v1/audio/fetch \
  -H "Authorization: Bearer $NIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "3f2a1c9e-..."}'
# → {"task_id": "...", "status": "completed", "files": [{"url": "https://cdn.nixai.ru/cdn/....mp3", ...}]}
```

## Аутентификация

Все запросы требуют заголовок:

```
Authorization: Bearer <ваш API-ключ>
```

## Модели

| Модель | Особенности | Максимум символов в запросе | Цена за 1 000 символов |
| - | - | -: | -: |
| `eleven_v3` | Самое выразительное звучание, поддержка тегов эмоций, 70+ языков | 50 000 | \$0.10 |
| `eleven_v4` | — | 50 000 | \$0.08 |
| `eleven_v4_turbo` | — | 50 000 | \$0.04 |

Для `eleven_v3` один символ текста стоит один кредит.

## Создание задачи

```
POST /v1/audio/speech/generations
```

### Тело запроса

```json theme={null}
{
  "model": "eleven_v3",
  "input": "Текст для озвучки.",
  "voice": "CwhRBWXzGAHq8TQ4Fs17",
  "voice_settings": {
    "stability": 0.5,
    "similarity_boost": 0.75,
    "style": 0.0,
    "use_speaker_boost": true
  },
  "language_code": "ru",
  "seed": 12345
}
```

| Поле | Тип | Обязательно | Описание |
| - | - | - | - |
| `model` | string | да | Одна из моделей таблицы выше |
| `input` | string | да | Непустой текст для озвучки. Лимит зависит от модели |
| `voice` | string | да | Идентификатор голоса из `GET /v1/audio/voices` или `GET /v1/audio/voices/library` |
| `voice_settings` | object | нет | Тонкая настройка голоса |
| `language_code` | string | нет | Код языка ISO 639-1 (`ru`, `en`, `de` и т. д.) |
| `seed` | integer | нет | Значение от 0 до 4294967295. Повышает воспроизводимость, но не гарантирует её |

### `voice_settings`

| Поле | Диапазон | По умолчанию | Смысл |
| - | -: | -: | - |
| `stability` | 0.0–1.0 | 0.5 | Ниже — эмоциональнее и вариативнее, выше — ровнее и предсказуемее |
| `similarity_boost` | 0.0–1.0 | 0.75 | Насколько точно воспроизводить характер голоса |
| `style` | 0.0–1.0 | 0.0 | Усиление стилистической окраски. Значения выше 0 замедляют синтез |
| `use_speaker_boost` | boolean | true | Усиление сходства с оригинальным голосом |

Ответ создаётся мгновенно, синтез выполняется в фоне:

```json theme={null}
{ "task_id": "3f2a1c9e-8b4d-4e1f-9c2a-7d6e5f4a3b2c" }
```

## Получение результата

```
POST /v1/audio/fetch
```

### Тело запроса

```json theme={null}
{ "id": "3f2a1c9e-8b4d-4e1f-9c2a-7d6e5f4a3b2c" }
```

| Поле | Тип | Обязательно | Описание |
| - | - | - | - |
| `id` | string | да | `task_id`, полученный при создании |

Во время синтеза:

```json theme={null}
{
  "task_id": "3f2a1c9e-...",
  "status": "processing",
  "progress": 62,
  "files": [],
  "service_files": [],
  "data": null
}
```

`progress` — целое число от 0 до 100.

После завершения:

```json theme={null}
{
  "task_id": "3f2a1c9e-...",
  "status": "completed",
  "progress": 100,
  "files": [
    {
      "kind": "result",
      "url": "https://cdn.nixai.ru/cdn/4a1b2c3d....mp3",
      "type": "audio/mpeg",
      "duration": 184.32,
      "bytes": 2948912
    }
  ],
  "service_files": [],
  "data": null,
  "credits": 3117
}
```

Для синтеза речи в `files` всегда один элемент — готовая склеенная дорожка целиком.

### Статусы

| Статус | Финальный | Списание | Описание |
| - | - | - | - |
| `processing` | нет | — | Синтез идёт, продолжайте опрашивать |
| `completed` | да | да | Файл готов, ссылка находится в `files` |
| `rejected` | да | нет | Запрос отклонён модерацией или из-за невалидного входа |
| `failed` | да | нет | Внутренняя ошибка. Повторите запрос |

Деньги списываются только за `completed`.

### Рекомендуемый опрос

Интервал между запросами — 2–3 секунды. Короткий текст готов за секунды, десятки тысяч символов — за минуты.

```python theme={null}
import time
import requests

API = "https://api.nixai.ru"
H = {"Authorization": f"Bearer {KEY}"}

task = requests.post(f"{API}/v1/audio/speech/generations", headers=H, json={
    "model": "eleven_v3",
    "input": "Текст для озвучки.",
    "voice": "CwhRBWXzGAHq8TQ4Fs17",
}).json()

while True:
    result = requests.post(f"{API}/v1/audio/fetch", headers=H,
                           json={"id": task["task_id"]}).json()
    if result["status"] != "processing":
        break
    time.sleep(2)

if result["status"] == "completed":
    audio = requests.get(result["files"][0]["url"]).content
    with open("result.mp3", "wb") as file:
        file.write(audio)
else:
    print("failed:", result.get("error"), result.get("message"))
```

## Разметка текста

### Паузы

Вставьте `{{pause=N}}`, где `N` — секунды (дробные значения допускаются, разделитель — точка или запятая):

```
Первая глава.{{pause=2}}Прошло три года.{{pause=0.5}}Всё изменилось.
```

* Пауза не тарифицируется: разметка удаляется до синтеза.
* Одна пауза — до 10 секунд, всего — до 100 пауз, суммарная тишина — до 120 секунд.
* Пауза в начале текста создаёт тишину перед началом речи.

`eleven_v3` понимает теги эмоций и действий в квадратных скобках: `[whispers]`, `[laughs]`, `[sighs]`, `[excited]` и другие. Модель также понимает `<break time="1.5s" />` для коротких пауз внутри фразы. Эти теги передаются модели как есть и тарифицируются как обычный текст; для длинных пауз выгоднее `{{pause=N}}`.

## Голоса

### Голоса по умолчанию

```
GET /v1/audio/voices
```

Эндпоинт возвращает готовые к использованию голоса:

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "voice_id": "CwhRBWXzGAHq8TQ4Fs17",
      "name": "Roger - Laid-Back, Casual, Resonant",
      "category": "premade",
      "description": "...",
      "labels": { "accent": "american", "gender": "male", "age": "middle_aged" },
      "preview_url": "https://.../preview.mp3",
      "verified_languages": [
        { "language": "en", "model_id": "eleven_v3", "accent": "american" }
      ]
    }
  ]
}
```

`verified_languages` показывает, для каких языков и моделей голос проверен. Голос можно использовать и с другими моделями, но качество проверенных сочетаний предсказуемее.

### Библиотека голосов

```
GET /v1/audio/voices/library
```

Библиотека содержит более 17 000 голосов сообщества. Параметры поиска: `page_size` (1–100, по умолчанию 30), `page` (с 0), `category` (`professional`, `famous`, `high_quality`), `gender` (`male`, `female`, `neutral`), `age` (`young`, `middle_aged`, `old`), `accent`, `language`, `locale` и `search`.

```bash theme={null}
curl "https://api.nixai.ru/v1/audio/voices/library?language=ru&gender=female&page_size=10" \
  -H "Authorization: Bearer $NIXAI_API_KEY"
```

Используйте `voice_id` из ответа в поле `voice` при создании задачи. Для перебора страниц ориентируйтесь на `has_more`; `total_count` приблизителен и меняется по мере пополнения библиотеки.

## Ошибки

Ошибки возвращаются в едином формате:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "text_too_long",
    "message": "Input is 61204 characters, the limit for this model is 50000.",
    "param": "input"
  }
}
```

### При создании задачи

| HTTP | `code` | Причина |
| -: | - | - |
| 400 | `text_empty` | Пустой `input` |
| 400 | `text_not_voiceable` | В тексте нет произносимых символов |
| 400 | `text_too_long` | Превышен лимит символов |
| 400 | `pause_invalid` | Некорректное значение `{{pause=...}}` |
| 400 | `pause_too_long` | Одна пауза длиннее 10 секунд |
| 400 | `too_many_pauses` | Больше 100 пауз |
| 400 | `total_silence_too_long` | Суммарная тишина больше 120 секунд |
| 400 | `voice_required` | Не указан `voice` |
| 404 | `model_not_found` | Неизвестная модель |
| 403 | `insufficient_quota` | Недостаточно средств |
| 503 | `no_channels_available` | Сервис временно недоступен |

Все эти ошибки возвращаются до создания задачи и ничего не стоят.

### В поле `error` задачи (статус `rejected`)

`content_policy_violation` — текст отклонён модерацией; `voice_not_found` — голос не существует; `invalid_request` — прочая ошибка параметров.

### При получении результата

`404 not_found` означает, что задачи с таким `id` нет или она принадлежит другому ключу.

## Лимиты и особенности

* Длина текста ограничена 50 000 символами. Считаются все символы, включая пробелы и разметку.
* Ссылка на результат живёт один час после завершения — скачайте файл сразу.
* Списание происходит только за успешно завершённые задачи. `{{pause}}` бесплатны, квадратные теги и `<break />` тарифицируются.
* Длинный текст режется по границам предложений. Интонация между фрагментами сохраняется, фразы не рвутся посередине.
* Задачи изолированы по API-ключу: результат доступен только ключу, создавшему задачу.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.