doc: полная документация Whisper API (ProxyAPI.ru) — параметры, форматы, verbose_json, word timestamps
This commit is contained in:
“Naeel”
@@ -0,0 +1,271 @@
|
|||||||
|
# Whisper API — Распознавание речи (ProxyAPI.ru)
|
||||||
|
|
||||||
|
> Источники:
|
||||||
|
> - [ProxyAPI.ru — Распознавание речи OpenAI API](https://proxyapi.ru/docs/openai-speech-to-text)
|
||||||
|
> - Тестирование через `curl` с реальными запросами (2026-05-23)
|
||||||
|
> - [OpenAI Speech-to-Text Guide](https://platform.openai.com/docs/guides/speech-to-text) (официальный, заблокирован из РФ)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Endpoint
|
||||||
|
|
||||||
|
```
|
||||||
|
POST https://api.proxyapi.ru/openai/v1/audio/transcriptions
|
||||||
|
```
|
||||||
|
|
||||||
|
Авторизация: `Authorization: Bearer <API_KEY>`
|
||||||
|
|
||||||
|
Второй endpoint — перевод в английский:
|
||||||
|
```
|
||||||
|
POST https://api.proxyapi.ru/openai/v1/audio/translations
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Модели
|
||||||
|
|
||||||
|
| Модель | Форматы ответа | Временные метки | Поток |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `whisper-1` | json, text, srt, verbose_json, vtt | ✅ word + segment | ❌ |
|
||||||
|
| `gpt-4o-transcribe` | json, text | ❌ | ✅ |
|
||||||
|
| `gpt-4o-mini-transcribe` | json, text | ❌ | ✅ |
|
||||||
|
|
||||||
|
**Вывод:** для максимальной детализации (сегменты, слова,置信度) — только `whisper-1`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Параметры запроса
|
||||||
|
|
||||||
|
| Параметр | Тип | Обязательный | Описание |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `file` | file | ✅ | Аудиофайл (mp3, mp4, mpeg, mpga, m4a, wav, webm). Макс 25 МБ |
|
||||||
|
| `model` | string | ✅ | `whisper-1`, `gpt-4o-transcribe`, `gpt-4o-mini-transcribe` |
|
||||||
|
| `language` | string | ❌ | ISO-639-1 код (`it`, `en`, `ru`, ...). Без него — автоопределение |
|
||||||
|
| `prompt` | string | ❌ | Текст-подсказка: термины, имена, аббревиатуры для улучшения точности |
|
||||||
|
| `temperature` | float | ❌ | 0–1. По умолчанию 0. Выше = разнообразнее, но больше ошибок |
|
||||||
|
| `response_format` | string | ❌ | `json` (по умолч.), `text`, `srt`, `verbose_json`, `vtt` |
|
||||||
|
| `timestamp_granularities` | string[] | ❌ | `["word"]`, `["segment"]`, `["word","segment"]`. Только для `whisper-1` |
|
||||||
|
|
||||||
|
### ⚠️ Важный нюанс (webm)
|
||||||
|
|
||||||
|
ProxyAPI.ru **заявляет** поддержку `webm`, но по факту ffmpeg на их стороне **не может определить длительность** webm/opus файлов из Chrome. Ошибка:
|
||||||
|
```json
|
||||||
|
{"detail": "Cannot extract audio duration. Invalid file or format."}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Решение:** конвертировать webm → WAV (16kHz, mono) в браузере через Web Audio API перед отправкой.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Форматы ответа
|
||||||
|
|
||||||
|
### 4.1 `json` (по умолчанию)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"text": "распознанный текст"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
С `usage` (зависит от модели):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"text": "Sottotitoli e revisione a cura di QTSS",
|
||||||
|
"usage": {
|
||||||
|
"type": "duration",
|
||||||
|
"seconds": 2
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 `text`
|
||||||
|
|
||||||
|
Чистый текст, без JSON:
|
||||||
|
```
|
||||||
|
Sottotitoli e revisione a cura di QTSS
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 `verbose_json`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"task": "transcribe",
|
||||||
|
"language": "italian",
|
||||||
|
"duration": 2.0,
|
||||||
|
"text": "Sottotitoli e revisione a cura di QTSS",
|
||||||
|
"segments": [
|
||||||
|
{
|
||||||
|
"id": 0,
|
||||||
|
"seek": 0,
|
||||||
|
"start": 0.0,
|
||||||
|
"end": 2.0,
|
||||||
|
"text": " Sottotitoli e revisione a cura di QTSS",
|
||||||
|
"tokens": [50364, 318, 1521, 310, 270, 9384, 308, 34218, 68, 257, 1262, 64, 1026, 1249, 7327, 50, 50464],
|
||||||
|
"temperature": 0.0,
|
||||||
|
"avg_logprob": -0.2574056088924408,
|
||||||
|
"compression_ratio": 0.8260869383811951,
|
||||||
|
"no_speech_prob": 0.8321689367294312
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"usage": {
|
||||||
|
"type": "duration",
|
||||||
|
"seconds": 2
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Поля сегмента:
|
||||||
|
|
||||||
|
| Поле | Описание |
|
||||||
|
|---|---|
|
||||||
|
| `id` | Номер сегмента (с 0) |
|
||||||
|
| `seek` | Смещение в секундах от начала файла |
|
||||||
|
| `start` | Начало сегмента (сек) |
|
||||||
|
| `end` | Конец сегмента (сек) |
|
||||||
|
| `text` | Текст сегмента |
|
||||||
|
| `tokens` | Идентификаторы токенов Whisper |
|
||||||
|
| `temperature` | Использованная температура |
|
||||||
|
| `avg_logprob` | Средняя лог-вероятность токенов (выше = увереннее). Можно использовать для оценки качества |
|
||||||
|
| `compression_ratio` | Степень сжатия текста относительно аудио |
|
||||||
|
| `no_speech_prob` | **Вероятность отсутствия речи** (0–1). Значения > 0.5 = вероятно тишина/шум |
|
||||||
|
|
||||||
|
### 4.4 `verbose_json` + `timestamp_granularities=["word"]`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"task": "transcribe",
|
||||||
|
"language": "italian",
|
||||||
|
"duration": 2.0,
|
||||||
|
"text": "Sottotitoli e revisione a cura di QTSS",
|
||||||
|
"words": [
|
||||||
|
{ "word": "Sottotitoli", "start": 0.0, "end": 0.48 },
|
||||||
|
{ "word": "e", "start": 0.48, "end": 0.56 },
|
||||||
|
{ "word": "revisione", "start": 0.56, "end": 1.12 },
|
||||||
|
{ "word": "a", "start": 1.12, "end": 1.20 },
|
||||||
|
{ "word": "cura", "start": 1.20, "end": 1.44 },
|
||||||
|
{ "word": "di", "start": 1.44, "end": 1.52 },
|
||||||
|
{ "word": "QTSS", "start": 1.52, "end": 2.0 }
|
||||||
|
],
|
||||||
|
"usage": { "type": "duration", "seconds": 2 }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
⚠️ При запросе `words`, поле `segments` **не возвращается** (взаимоисключающие).
|
||||||
|
|
||||||
|
### 4.5 `srt` / `vtt`
|
||||||
|
|
||||||
|
Форматы субтитров с таймкодами. Пример SRT:
|
||||||
|
```
|
||||||
|
1
|
||||||
|
00:00:00,000 --> 00:00:02,000
|
||||||
|
Sottotitoli e revisione a cura di QTSS
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Поддерживаемые языки
|
||||||
|
|
||||||
|
Полный список (из официальных доков):
|
||||||
|
|
||||||
|
Африкаанс, арабский, армянский, азербайджанский, белорусский, боснийский, болгарский,
|
||||||
|
каталанский, китайский, хорватский, чешский, датский, голландский, **английский**,
|
||||||
|
эстонский, финский, французский, галисийский, немецкий, греческий, иврит, хинди,
|
||||||
|
венгерский, исландский, индонезийский, **итальянский**, японский, каннада, казахский,
|
||||||
|
корейский, латышский, литовский, македонский, малайский, маратхи, маори, непальский,
|
||||||
|
норвежский, персидский, польский, португальский, румынский, **русский**, сербский,
|
||||||
|
словацкий, словенский, испанский, суахили, шведский, тагальский, тамильский, тайский,
|
||||||
|
турецкий, украинский, урду, вьетнамский, валлийский.
|
||||||
|
|
||||||
|
Коды ISO-639-1: `it` (итальянский), `en` (английский), `ru` (русский), `fr` (французский), etc.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Prompt — улучшение распознавания
|
||||||
|
|
||||||
|
Параметр `prompt` помогает Whisper правильно распознать специфические термины,
|
||||||
|
имена, аббревиатуры. Работает как контекстная подсказка.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"model": "whisper-1",
|
||||||
|
"file": "@audio.wav",
|
||||||
|
"language": "it",
|
||||||
|
"prompt": "amore, cuore, spaghetti, Ferrari, Lamborghini, ciao, buongiorno"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Рекомендация:** передавать ожидаемое слово/фразу как prompt для повышения точности.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Полезные поля для оценки качества
|
||||||
|
|
||||||
|
### `avg_logprob` (средняя лог-вероятность)
|
||||||
|
- Диапазон: примерно от -2.0 (плохо) до 0 (идеально)
|
||||||
|
- Можно использовать как confidence score
|
||||||
|
- Порог ~ -0.5 для приемлемого качества
|
||||||
|
|
||||||
|
### `no_speech_prob` (вероятность тишины)
|
||||||
|
- 0 = точно речь
|
||||||
|
- 1 = точно тишина/шум
|
||||||
|
- Порог > 0.5 = вероятно, сказать нечего
|
||||||
|
|
||||||
|
### `compression_ratio`
|
||||||
|
- Отношение длины текста к длине аудио
|
||||||
|
- Аномальные значения могут указывать на галлюцинации
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Ограничения
|
||||||
|
|
||||||
|
- Макс. размер файла: **25 МБ**
|
||||||
|
- Перевод (`/translations`) — **только на английский**
|
||||||
|
- Временные метки — **только `whisper-1`**
|
||||||
|
- Поток (`stream=true`) — **недоступен для `whisper-1`**
|
||||||
|
- `webm` заявлен но **не работает** с ProxyAPI.ru (нужна конвертация в WAV/MP3)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Цены (ProxyAPI.ru, май 2026)
|
||||||
|
|
||||||
|
| Модель | Цена за минуту |
|
||||||
|
|---|---|
|
||||||
|
| `whisper-1` | ~0.006 $ |
|
||||||
|
| `gpt-4o-transcribe` | ~0.006 $ |
|
||||||
|
| `gpt-4o-mini-transcribe` | ~0.003 $ |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Пример использования в Lyngvo
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// transcribe.js — актуальная версия (v103)
|
||||||
|
async function blobToWav(blob) {
|
||||||
|
const ab = await blob.arrayBuffer();
|
||||||
|
const ctx = new AudioContext({ sampleRate: 16000 });
|
||||||
|
const buf = await ctx.decodeAudioData(ab);
|
||||||
|
await ctx.close();
|
||||||
|
// ... конвертация в WAV 16kHz mono ...
|
||||||
|
return new Blob([wavBuf], { type: 'audio/wav' });
|
||||||
|
}
|
||||||
|
|
||||||
|
async function transcribe(blob) {
|
||||||
|
const wavBlob = await blobToWav(blob);
|
||||||
|
const fd = new FormData();
|
||||||
|
fd.append('file', wavBlob, 'audio.wav');
|
||||||
|
fd.append('model', 'whisper-1');
|
||||||
|
fd.append('language', 'it');
|
||||||
|
// По желанию — prompt для улучшения точности
|
||||||
|
// fd.append('prompt', 'amore, ciao, buongiorno');
|
||||||
|
|
||||||
|
const r = await fetch(
|
||||||
|
'https://api.proxyapi.ru/openai/v1/audio/transcriptions',
|
||||||
|
{
|
||||||
|
method: 'POST',
|
||||||
|
headers: { 'Authorization': `Bearer ${API_KEY}` },
|
||||||
|
body: fd
|
||||||
|
}
|
||||||
|
);
|
||||||
|
return await r.json();
|
||||||
|
// → { text: "...", usage: { type: "duration", seconds: N } }
|
||||||
|
}
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user