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

# OpenAI API для распознавания речи (/v1/audio/transcriptions)

> OpenAI generation API guide - Ace Data Cloud

Преобразуйте аудио в текст, **полностью совместимо с OpenAI `/v1/audio/transcriptions`**. Любой SDK OpenAI просто указывает `base_url` на `https://api.acedata.cloud` и заменяет ключ на ваш AceData Token для непосредственного использования. Поддерживает обычный полный ответ, а также инкрементальную транскрипцию SSE для `gpt-transcribe`.

* **Адрес запроса**: `POST https://api.acedata.cloud/v1/audio/transcriptions` (псевдоним `POST /openai/audio/transcriptions`)
* **Аутентификация**: заголовок запроса `Authorization: Bearer {token}`
* **Формат запроса**: `multipart/form-data`
* **Оплата**: по длительности аудио (см. таблицу ниже), менее 1 секунды считается как 1 секунда.

## Параметры запроса

| Поле | Тип | Обязательное | Описание |
| - | - | - | - |
| `file` | file | Да | Аудиофайл для транскрипции, максимальный размер 25 МБ. Поддерживает `flac`, `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `ogg`, `wav`, `webm`. |
| `model` | string | Нет | `whisper-1` (по умолчанию) или `gpt-transcribe`, различия в возможностях см. в таблице ниже. |
| `language` | string | Нет | Язык аудио, код ISO-639-1 (например, `zh`, `en`). Заполнение может повысить точность и скорость; оставьте пустым для автоматического распознавания. |
| `prompt` | string | Нет | Подсказка, используемая для направления стиля написания или предоставления собственных имен, терминов для повышения точности распознавания. |
| `response_format` | string | Нет | `whisper-1`: `json` (по умолчанию), `text`, `srt`, `verbose_json`, `vtt`; `gpt-transcribe`: только `json`, `text`. |
| `temperature` | number | Нет | Температура выборки 0–1, по умолчанию 0. |
| `timestamp_granularities[]` | array | Нет | Гранулярность временных меток, `word` или `segment`, необходимо использовать с `response_format=verbose_json`. |
| `languages[]` | array | Нет | Альтернативные языки (ISO-639-1), **только `gpt-transcribe`**. Взаимно исключает с `language`, не передавайте одновременно. |
| `keywords[]` | array | Нет | Подсказки по собственным именам/терминам, **только `gpt-transcribe`**, могут значительно повысить точность распознавания брендов и имен. |
| `stream` | boolean | Нет | При установке `gpt-transcribe` в `true` возвращает события инкрементальной SSE; `whisper-1` игнорирует этот параметр и возвращает полный результат (в соответствии с официальным поведением OpenAI). |

## Какой модель выбрать

| | `whisper-1` | `gpt-transcribe` |
| - | - | - |
| Цена | \$0.0078 / минута | **\$0.0059 / минута** (дешевле) |
| Точность распознавания | Хорошо | **Лучше**, особенно для имен брендов и собственных имен |
| Вывод субтитров (`srt`/`vtt`) | ✅ | ❌ |
| Временные метки на уровне слов | ✅ | ❌ |
| `languages[]` / `keywords[]` | ❌ | ✅ |
| Возврат обнаруженного языка | требуется `verbose_json` | возвращается по умолчанию |
| Инкрементальный возврат SSE | ❌ (параметр `stream` игнорируется) | ✅ |

**Нужны субтитры или временные метки на уровне слов → `whisper-1`; для остальных случаев рекомендуется `gpt-transcribe`** (более точно и дешевле).

## Пример

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=whisper-1
```

Возврат:

```json theme={null}
{
  "text": "Ace Data Cloud Platform is testing the speech recognition endpoint. The quick brown fox jumps over the lazy dog."
}
```

Китайское аудио также поддерживается, язык указывать не нужно:

```json theme={null}
{
  "text": "欢迎使用 AceData Cloud 平台,我们正在测试语音识别接口,今天是 7 月 31 号。"
}
```

### Генерация субтитров

Установите `response_format` в `srt` или `vtt`, чтобы получить готовый файл субтитров:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=whisper-1 \
  -F response_format=srt \
  -o subtitle.srt
```

Возвращаемое содержимое (`Content-Type: text/plain`):

```
1
00:00:00,000 --> 00:00:03,800
Ace Data Cloud Platform is testing the speech recognition endpoint.

2
00:00:03,800 --> 00:00:06,280
The quick brown fox jumps over the lazy dog.
```

### Временные метки на уровне слов

Если нужны временные метки для каждого слова, используйте `verbose_json` вместе с `timestamp_granularities[]=word`:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=whisper-1 \
  -F response_format=verbose_json \
  -F 'timestamp_granularities[]=word'
```

Возврат:

```json theme={null}
{
  "task": "transcribe",
  "language": "english",
  "duration": 6.29,
  "text": "Ace Data Cloud Platform is testing the speech recognition endpoint. The quick brown fox jumps over the lazy dog.",
  "words": [
    {
      "word": "Ace",
      "start": 0.0,
      "end": 0.32
    },
    {
      "word": "Data",
      "start": 0.32,
      "end": 0.54
    },
    {
      "word": "Cloud",
      "start": 0.54,
      "end": 0.86
    }
  ]
}
```

### Потоковая транскрипция

`gpt-transcribe` может возвращать `Content-Type: text/event-stream` с `stream=true`. Сервис будет отправлять события, совместимые с OpenAI:
`transcript.text.delta` содержит инкрементальный текст, `transcript.text.done` содержит полный текст и `usage`, указывая на нормальное завершение.

```shell theme={null}
curl -N -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=gpt-transcribe \
  -F stream=true
```

Пример потока событий:

```text theme={null}
data: {"type":"transcript.text.delta","delta":"Hello"}

data: {"type":"transcript.text.done","text":"Hello world","usage":{"type":"tokens","input_tokens":14,"output_tokens":3,"total_tokens":17}}
```

Получение `transcript.text.done` означает нормальное завершение. Если после установления потока произойдет ошибка обработки, соединение завершится после события `event: error`; если клиент отключится, это отменит текущую обработку и не будет продолжать в фоновом режиме. `whisper-1`, даже если передан `stream=true`, все равно вернет обычный не потоковый ответ.

### Использование официального SDK

```python theme={null}
from openai import OpenAI

client = OpenAI(base_url="https://api.acedata.cloud/v1", api_key="{token}")
with open("audio.mp3", "rb") as f:
    result = client.audio.transcriptions.create(model="whisper-1", file=f)
print(result.text)
```

## Цены

| Модель | Цена на платформе |
| - | - |
| `whisper-1` | \$0.0078 / минута |
| `gpt-transcribe` | \$0.0059 / минута |

> Оплата производится по фактической продолжительности аудио, менее 1 секунды округляется до 1 секунды, максимальная продолжительность одной транскрипции — 1 час.

## Важные замечания

* Максимальный размер одного файла **25 MB**. Если превышает, сначала разделите или сожмите (обычно достаточно снизить битрейт, требования к качеству звука для распознавания речи не высоки).
* `gpt-transcribe` поддерживает `stream=true` SSE; `whisper-1` игнорирует `stream` и возвращает полный результат.
* Параметры соответствуют официальному OpenAI `/v1/audio/transcriptions`, официальный SDK требует только изменения `base_url` для использования.
* `include[]`, `chunking_strategy`, `known_speaker_names[]`, `known_speaker_references[]` относятся к нашим не выпущенным моделям транскрипции, передача приведет к ошибке 400, а не к тихому игнорированию. Специфические параметры модели (`timestamp_granularities[]` для `whisper-1`, `languages[]`/`keywords[]` для `gpt-transcribe`) также вернут 400 при передаче неподдерживаемым моделям.
* Запросы могут занимать много времени, рекомендуется устанавливать тайм-аут клиента не менее 300 секунд.

## Коды ошибок

| Код состояния | code | Описание |
| - | - | - |
| 400 | `bad_request` | Не предоставлен `file`, файл не может быть обработан или параметры недействительны (`model`/`response_format` недопустимые значения, `temperature` вне диапазона 0–1, `timestamp_granularities[]` не совместим с `verbose_json`, переданы неподдерживаемые параметры для `whisper-1`). |
| 401 | `authentication_failed` | Токен недействителен. |
| 403 | `used_up` | Недостаточно средств. |
| 413 | `request_too_large` | Аудиофайл превышает лимит в 25 MB. |
| 429 | `too_many_requests` | Запросы слишком частые, пожалуйста, попробуйте позже. |
| 500 | `api_error` | Внутренняя ошибка сервиса, пожалуйста, попробуйте позже. |


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