> ## 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/transcriptions — текст из аудиозаписи с таймкодами и диаризацией

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

## Три способа передать аудио

**Файл в multipart** — до 25 МиБ. Поле `file`:

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

curl https://speshu.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -F "model=$MODEL" \
  -F "file=@speech.mp3"
```

**Base64 в JSON** — поле `input_audio` с объектом `{data, format}`; аудио — строкой base64 без префикса `data:...;base64,`:

```bash cURL theme={null} theme={null}
AUDIO=$(base64 -w0 speech.mp3)
curl https://speshu.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL\",
    \"input_audio\": { \"data\": \"$AUDIO\", \"format\": \"mp3\" }
  }"
```

**Ссылка** — поле `source_url` с публичным адресом записи:

```bash cURL theme={null} theme={null}
curl https://speshu.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL\",
    \"source_url\": \"https://example.com/records/interview.mp3\"
  }"
```

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

> [!WARNING]
>
> Передайте аудио ровно одним способом: `file`, `input_audio` или `source_url`. Ограничение в 25 МиБ относится к файлу в multipart; для двух других способов ограничением остаётся обычный лимит тела JSON-запроса.

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

| Поле | Тип | Описание |
| - | - | - |
| `model` | string | Идентификатор модели из каталога с `capabilities`, содержащим `"transcription"`. Обязательно |
| `file` | file | Аудиофайл в multipart, до 25 МиБ. Ровно один из `file`, `input_audio`, `source_url` |
| `input_audio` | object | Объект `{data, format}`: аудио в base64 и формат. Формат необязателен — большинство провайдеров определяют его по содержимому. Ровно один из `file`, `input_audio`, `source_url` |
| `source_url` | string | Публичная ссылка на запись. Ровно один из `file`, `input_audio`, `source_url` |
| `language` | string | Язык записи подсказкой модели, например `"ru"`. Необязательно |
| `response_format` | string | Формат ответа: `json` (по умолчанию) или `verbose_json`. Необязательно |
| `diarize` | boolean | Разметка реплик по говорящим. Работает **только** с `response_format: "verbose_json"` |
| `keyterms` | array | Список терминов, имён и аббревиатур, которые модель должна распознавать точнее. Необязательно |
| `timestamp_granularities` | array | Гранулярность таймкодов, например `["segment"]`. Применяется с `verbose_json`. Необязательно |
| `temperature` | number | Температура сэмплирования модели. Необязательно |

> [!WARNING]
>
> `diarize` без `response_format: "verbose_json"` — ошибка запроса: разметке по говорящим нужно место в ответе, которого компактный `json` не имеет.

## Ответ

`200 OK` с форматом по умолчанию `json`:

```json theme={null} theme={null}
{
  "text": "Полный текст записи одним полем."
}
```

С `response_format: "verbose_json"` ответ несёт сегменты с таймкодами, а с включённой `diarize` — и говорящего каждого сегмента:

```json theme={null} theme={null}
{
  "text": "Полный текст записи одним полем.",
  "segments": [
    {
      "text": "Добро пожаловать на встречу.",
      "start": 0.0,
      "end": 2.4,
      "speaker": "SPEAKER_0"
    },
    {
      "text": "Спасибо, начинаем.",
      "start": 2.6,
      "end": 4.1,
      "speaker": "SPEAKER_1"
    }
  ],
  "usage": {
    "seconds": 61,
    "input_tokens": 21,
    "output_tokens": 11,
    "total_tokens": 32,
    "cost": 0.45
  }
}
```

| Поле | Тип | Описание |
| - | - | - |
| `text` | string | Полный распознанный текст |
| `segments` | array | Только с `verbose_json`. Сегменты с границами по времени |
| `segments[].speaker` | string | Только с `diarize`. Метка говорящего сегмента |
| `usage.seconds` | number | Длительность обработанного аудио в секундах |
| `usage.input_tokens` / `usage.output_tokens` / `usage.total_tokens` | integer | Токены (у моделей с токенной тарификацией) |
| `usage.cost` | number | Сумма, списанная с вашего баланса за вызов. Поле отсутствует, если списание не зафиксировано |

Точный состав полей сегмента зависит от `timestamp_granularities` и модели — проверяйте наличие полей перед чтением.

### Стоимость

Как у ранжирования: списание зависит от фактической стоимости вызова. Поле `usage.cost` — сумма, списанная с вашего баланса; оно отсутствует, если списание не зафиксировано. Фактический остаток после вызова проверяйте через `GET /api/v1/balance`.

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

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

| Ситуация | Ответ |
| - | - |
| Нет ключа или ключ недействителен | `401 invalid_api_key` |
| Модель не из списка моделей распознавания | `404 model_not_found` |
| Не хватает денег | `402 insufficient_quota` |
| Нет `model`; аудио не передано или передано больше чем одним способом | `400 invalid_request` |
| Файл больше 25 МиБ | `400 invalid_request` |
| `diarize` без `response_format: "verbose_json"` | `400 invalid_request` |

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

## Что дальше

> [card] [Синтез речи](https://speshu.ai/docs/api-reference/audio/speech.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/transcriptions
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/transcriptions:
    post:
      tags:
        - Аудио
      summary: Распознавание речи
      description: >-
        Превращает аудиозапись в текст. Аудио передаётся одним из трёх способов:
        файл в multipart (до 25 МиБ), строка base64 в поле input_audio или
        ссылка в поле source_url. Модель берётся из каталога GET /api/v1/models
        — у неё в capabilities есть значение "transcription". Списание зависит
        от фактической стоимости вызова.
      operationId: createTranscription
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateTranscriptionForm'
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTranscriptionRequest'
      responses:
        '200':
          description: Распознанный текст; с verbose_json — сегменты с таймкодами и usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscriptionResponse'
        '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:
    CreateTranscriptionForm:
      type: object
      required:
        - model
        - file
      properties:
        model:
          type: string
          description: >-
            Идентификатор модели из GET /api/v1/models: у неё в capabilities
            есть значение "transcription". Передаётся как есть.
        language:
          type: string
          description: Подсказка языка записи, например "ru". Необязательно.
        response_format:
          type: string
          enum:
            - json
            - verbose_json
          description: >-
            Формат ответа: json (по умолчанию) или verbose_json с сегментами и
            usage.
        diarize:
          type: boolean
          description: >-
            Разметка реплик по говорящим. Работает только с response_format
            "verbose_json".
        keyterms:
          type: array
          items:
            type: string
          description: >-
            Термины, имена и аббревиатуры для точного распознавания.
            Необязательно.
        timestamp_granularities:
          type: array
          items:
            type: string
          description: >-
            Гранулярность таймкодов, например ["segment"]. Применяется с
            verbose_json. Необязательно.
        temperature:
          type: number
          description: Температура сэмплирования. Необязательно.
        file:
          type: string
          format: binary
          description: Аудиофайл, до 25 МиБ.
    CreateTranscriptionRequest:
      type: object
      required:
        - model
      properties:
        model:
          type: string
          description: >-
            Идентификатор модели из GET /api/v1/models: у неё в capabilities
            есть значение "transcription". Передаётся как есть.
        language:
          type: string
          description: Подсказка языка записи, например "ru". Необязательно.
        response_format:
          type: string
          enum:
            - json
            - verbose_json
          description: >-
            Формат ответа: json (по умолчанию) или verbose_json с сегментами и
            usage.
        diarize:
          type: boolean
          description: >-
            Разметка реплик по говорящим. Работает только с response_format
            "verbose_json".
        keyterms:
          type: array
          items:
            type: string
          description: >-
            Термины, имена и аббревиатуры для точного распознавания.
            Необязательно.
        timestamp_granularities:
          type: array
          items:
            type: string
          description: >-
            Гранулярность таймкодов, например ["segment"]. Применяется с
            verbose_json. Необязательно.
        temperature:
          type: number
          description: Температура сэмплирования. Необязательно.
        input_audio:
          type: object
          description: Аудиозапись в base64. Ровно один из input_audio, source_url.
          required:
            - data
          properties:
            data:
              type: string
              description: Аудио в base64 без префикса data:...;base64,.
            format:
              type: string
              description: >-
                Формат аудио, например wav или mp3. Необязательно — большинство
                провайдеров определяют формат по содержимому.
        source_url:
          type: string
          description: Публичная ссылка на запись. Ровно один из input_audio, source_url.
    TranscriptionResponse:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: Полный распознанный текст.
        segments:
          type: array
          description: 'Только с verbose_json: сегменты с границами по времени.'
          items:
            type: object
            properties:
              text:
                type: string
                description: Текст сегмента.
              start:
                type: number
                description: Начало сегмента, секунды.
              end:
                type: number
                description: Конец сегмента, секунды.
              speaker:
                type: string
                description: 'Только с diarize: метка говорящего.'
        usage:
          type: object
          properties:
            seconds:
              type: number
              description: Длительность обработанного аудио в секундах.
            input_tokens:
              type: integer
              description: Входные токены.
            output_tokens:
              type: integer
              description: Выходные токены.
            total_tokens:
              type: integer
              description: Суммарные токены.
            cost:
              type: number
              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.