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

# Синтез речи

> POST /api/v1/audio/speech — превращение текста в аудиопоток

Эндпоинт превращает текст в речь и возвращает готовый аудиопоток. Работает с моделями из каталога `GET /api/v1/models`, у которых в `capabilities` есть значение `"speech"`.

## Минимальный запрос

Сначала получите идентификатор модели из каталога, отфильтровав его по `capabilities`:

```bash cURL theme={null} theme={null}
MODEL=$(curl -s https://speshu.ai/api/v1/models \
  | jq -r '.data[] | select(.capabilities | index("speech")) | .id' \
  | head -n 1)

curl https://speshu.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL\",
    \"input\": \"Привет! Это синтез речи.\",
    \"voice\": \"alloy\",
    \"response_format\": \"mp3\"
  }" --output speech.mp3
```

> [!NOTE]
>
> Идентификатор модели берите из `GET /api/v1/models` и подставляйте **как есть**. Состав моделей меняется, поэтому в рабочем коде не зашивайте его литералом. Если передать идентификатор обычной текстовой модели или неизвестное значение, придёт `404` с кодом `model_not_found`.

## Поля запроса

| Поле | Тип | Описание |
| - | - | - |
| `model` | string | Идентификатор модели из каталога с `capabilities`, содержащим `"speech"`. Обязательно |
| `input` | string или array | Текст для озвучки: строка или массив реплик. Обязательно |
| `voice` | string | Голос озвучки. Необязательно — если модель не выбирает голос, провайдер возьмёт голос по умолчанию |
| `response_format` | string | Формат ответа: `pcm` или `mp3`. Необязательно |
| `speed` | number | Скорость речи. Необязательно |
| `instructions` | string | Указание модели, как читать текст: темп, тон, акценты. Необязательно |
| `input_references` | array | Референсы голоса для моделей, которые умеют клонировать голос по образцу. Необязательно |

## Ответ

Ответ — **бинарный аудиопоток**, а не JSON. Тело ответа пишите в файл или передавайте дальше в плеер напрямую; разбирать его как JSON не нужно. Поля `usage` в ответе нет.

Формат потока определяется полем `response_format` запроса: `pcm` — сырые сэмплы без заголовков, `mp3` — готовый аудиофайл.

> [!WARNING]
>
> Не проверяйте ответ через `response.json()` или аналогичный парсер — он упадёт на бинарных данных. Признак ошибки не в теле: при неудаче API вместо аудиопотока отвечает JSON с конвертом ошибки и соответствующим кодом состояния HTTP.

## Стоимость

Списание идёт за символы входного текста; для моделей с токенной тарификацией — по оценке входных токенов. Поля `usage` в ответе нет — списанную сумму проверяйте после вызова через `GET /api/v1/balance`.

## Проверки перед вызовом

Часть ошибок возвращается до обращения к модели:

| Ситуация | Ответ |
| - | - |
| Нет ключа или ключ недействителен | `401 invalid_api_key` |
| Модель не из списка моделей синтеза речи | `404 model_not_found` |
| Не хватает денег | `402 insufficient_quota` |
| Нет `model` или `input`, неверный `response_format` | `400 invalid_request` |

Ошибки приходят в конверте OpenAI — объект `error` с полями `message`, `type`, `param` и `code`. Полная таблица кодов — на странице [Ошибки](https://speshu.ai/docs/errors.md).

## Что дальше

> [card] [Распознавание речи](https://speshu.ai/docs/api-reference/audio/transcriptions.md)
>
> Текст из аудиозаписи

> [card] [Каталог моделей](https://speshu.ai/docs/api-reference/models/list.md)
>
> Фильтр по capabilities и цены моделей

> [card] [Баланс](https://speshu.ai/docs/api-reference/other/balance.md)
>
> Остаток кошелька по валютам

> [card] [Ошибки](https://speshu.ai/docs/errors.md)
>
> Полная таблица кодов


## OpenAPI

````yaml api-reference/openapi.json POST /api/v1/audio/speech
openapi: 3.1.0
info:
  title: SpeShu.AI API
  version: 1.0.0
  description: >-
    Единый OpenAI-совместимый API для текстовых моделей, генерации изображений,
    видео, аудио и музыки.


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


    Все запросы, кроме `GET /api/v1/models` и `GET /api/v1/media/models`,
    требуют API-ключ. Ключ передаётся в заголовке `Authorization: Bearer <ключ>`
    или `X-Api-Key: <ключ>`.


    ## Ошибки


    Текстовые эндпоинты (`/chat/completions`, `/responses`, `/messages`) и
    `/balance` возвращают ошибки в формате OpenAI:


    ```json

    { "error": { "message": "...", "type": "invalid_request_error", "param":
    null, "code": "invalid_request" } }

    ```


    Эндпоинты медиа используют собственный конверт:


    ```json

    { "code": 422, "msg": "...", "data": null }

    ```


    Подробности — на странице [Ошибки](/errors).
servers:
  - url: https://speshu.ai
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Текст
    description: Генерация текста и диалог
  - name: Медиа
    description: Асинхронные задачи генерации изображений, видео, аудио и музыки
  - name: Хранилище
    description: Файлы пользователя
  - name: Справочник
    description: Каталог моделей и баланс
  - name: Аудио
    description: Синтез и распознавание речи
  - name: Инструменты
    description: Поиск в интернете и загрузка страниц
paths:
  /api/v1/audio/speech:
    post:
      tags:
        - Аудио
      summary: Синтез речи
      description: >-
        Превращает текст в аудиопоток. Модель берётся из каталога GET
        /api/v1/models — у неё в capabilities есть значение "speech". Списание
        идёт за символы входного текста (для моделей с токенной тарификацией —
        по оценке входных токенов); поля usage в ответе нет.
      operationId: createSpeech
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpeechRequest'
      responses:
        '200':
          description: Бинарный аудиопоток формата response_format; тело не является JSON.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/OpenAIError'
        '401':
          $ref: '#/components/responses/OpenAIError'
        '402':
          $ref: '#/components/responses/OpenAIError'
        '403':
          $ref: '#/components/responses/OpenAIError'
        '404':
          $ref: '#/components/responses/OpenAIError'
        '422':
          $ref: '#/components/responses/OpenAIError'
        '429':
          $ref: '#/components/responses/OpenAIError'
        '499':
          $ref: '#/components/responses/OpenAIError'
        '500':
          $ref: '#/components/responses/OpenAIError'
        '502':
          $ref: '#/components/responses/OpenAIError'
        '503':
          $ref: '#/components/responses/OpenAIError'
        '504':
          $ref: '#/components/responses/OpenAIError'
components:
  schemas:
    CreateSpeechRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: >-
            Идентификатор модели из GET /api/v1/models: у неё в capabilities
            есть значение "speech". Передаётся как есть.
        input:
          description: 'Текст для озвучки: строка или массив реплик.'
        voice:
          type: string
          description: Голос озвучки.
        response_format:
          type: string
          enum:
            - pcm
            - mp3
          description: 'Формат ответа: pcm — сырые сэмплы, mp3 — готовый файл.'
        speed:
          type: number
          description: Скорость речи. Необязательно.
        instructions:
          type: string
          description: 'Указание, как читать текст: темп, тон, акценты. Необязательно.'
        input_references:
          type: array
          description: Референсы голоса для моделей с клонированием голоса. Необязательно.
    OpenAIError:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
              examples:
                - invalid_request_error
              description: >-
                `authentication_error` при 401, `rate_limit_error` при 429,
                `permission_error` при 403, в остальных случаях
                `invalid_request_error`, `api_error` или `internal_error`.
            param:
              type:
                - string
                - 'null'
            code:
              type:
                - string
                - 'null'
              examples:
                - invalid_request
              description: >-
                Машиночитаемый код: `invalid_api_key`, `unauthorized`,
                `insufficient_quota`, `rate_limit_exceeded`,
                `token_limit_exceeded`, `content_too_large`, `limit_exceeded`,
                `model_not_found`, `no_providers`, `service_unavailable`,
                `provider_error`, `invalid_request`, `context_length_exceeded`,
                `internal_error`.
          required:
            - message
            - type
      required:
        - error
  responses:
    OpenAIError:
      description: Ошибка в формате OpenAI.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API-ключ в формате `sk-...`. Альтернативно — заголовок `X-Api-Key:
        sk-...` (совместимо с Anthropic SDK).

````

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