> ## 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, і ви можете використовувати його безпосередньо. Підтримує звичайну повну відповідь, а також підтримує інкрементальне транскрибування `gpt-transcribe` через SSE.

* **Адреса запиту**: `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 тестує кінцеву точку розпізнавання мови. Швидка коричнева лисиця стрибає через ледачого собаку."
}
```

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

```json theme={null}
{
  "text": "Ласкаво просимо до платформи AceData Cloud, ми тестуємо інтерфейс розпізнавання мови, сьогодні 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
```

Повернене вміст (тип вмісту: text/plain):

```
1
00:00:00,000 --> 00:00:03,800
Платформа Ace Data Cloud тестує кінцеву точку розпізнавання мови.

2
00:00:03,800 --> 00:00:06,280
Швидка коричнева лисиця стрибає через ледачого собаку.
```

### Часові мітки на рівні слів

Якщо потрібно знати час початку та закінчення кожного слова, використовуйте `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 тестує кінцеву точку розпізнавання мови. Швидка коричнева лисиця стрибає через ледачого собаку.",
  "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":"Привіт"}

data: {"type":"transcript.text.done","text":"Привіт, світ","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.