Nail/lang
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: полная документация Whisper API (ProxyAPI.ru) — параметры, форматы, verbose_json, word timestamps

Browse Source
This commit is contained in:
“Naeel”
2026-05-23 14:34:32 +04:00
parent 3d6fb6107c
commit 7302d6ef62
1 changed files with 271 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/whisper-api.md
+271
View File
@@ -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 } }
}
```