JiriUhlir
76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
# Endpoint přepisu
|
|
|
|
Jediná metoda, která udělá vše najednou: přepis Deepgramem + OpenAI (whisper-1) a jejich
|
|
AI sloučení. Audio se posílá jako proměnná `file` (multipart/form-data), ostatní parametry
|
|
jsou form fields v POST. API klíče jsou v X- hlavičkách. Výstup je vždy JSON.
|
|
|
|
## Hlavičky (secrets)
|
|
|
|
| Hlavička | Nutná | Popis |
|
|
|----------|-------|-------|
|
|
| `X-Deepgram-Api-Key` | ano | Deepgram API klíč |
|
|
| `X-OpenAI-Api-Key` | ano | OpenAI API klíč (whisper-1 přepis + slučovací chat) |
|
|
|
|
## POST /dual-with-merge
|
|
|
|
### Form parametry
|
|
|
|
| Pole | Typ | Default | Popis |
|
|
|------|-----|---------|-------|
|
|
| `file` | soubor | — | Audio k přepisu (povinné) |
|
|
| `combine_prompt` | text | výchozí „Czech Transcript Merger“ | System prompt pro sloučení |
|
|
| `deepgram_model` | text | `nova-2` | Deepgram model |
|
|
| `whisper_model` | text | `whisper-1` | OpenAI přepisový model |
|
|
| `chat_model` | text | `gpt-4o` | OpenAI chat model pro sloučení |
|
|
| `language` | text | `cs` | Jazyk (ISO kód) |
|
|
| `diarize` | bool | `true` | Deepgram diarizace (rozlišení mluvčích) |
|
|
| `smart_format` | bool | `true` | Deepgram smart formatting |
|
|
|
|
Nezadá-li se `combine_prompt`, použije se výchozí prompt z `app/prompts.py`.
|
|
|
|
### Rozlišení mluvčích a kvalita
|
|
|
|
- Při `diarize=true` (výchozí) Deepgram interně zapne i `utterances` a přepis `deepgram`
|
|
se vrací se štítky mluvčích, např. `Mluvčí 0: ...` / `Mluvčí 1: ...`. Plochý přepis bez
|
|
mluvčích (samotné `alternatives[0].transcript`) se použije jen jako fallback.
|
|
- `gpt` (Whisper) je plynulý, ale **bez mluvčích** a občas halucinuje na tichu/šumu —
|
|
proto se volá s `temperature=0`.
|
|
- `merge` sjednotí oba zdroje: použije strukturu mluvčích z Deepgramu, doplní chybějící
|
|
repliky z Whisperu a ignoruje zjevné halucinace (řídí výchozí `combine_prompt`).
|
|
|
|
### Odpověď
|
|
|
|
```json
|
|
{
|
|
"gpt": "Dobrý den, tady je asistentka ...",
|
|
"deepgram": "Mluvčí 0: Dobrý den, tady je asistentka ...\nMluvčí 1: Ne, teď to nejde.",
|
|
"merge": "Asistent: Dobrý den, tady je asistentka ...\nVolající: Ne, teď to nejde."
|
|
}
|
|
```
|
|
|
|
### Příklad (curl)
|
|
|
|
```bash
|
|
curl -X POST https://services.csbot.cz/apps/audio-transcription/dual-with-merge \
|
|
-H "X-Deepgram-Api-Key: <DEEPGRAM_KEY>" \
|
|
-H "X-OpenAI-Api-Key: <OPENAI_KEY>" \
|
|
-F "file=@nahravka.mp3" \
|
|
-F "language=cs"
|
|
```
|
|
|
|
## Chybové stavy
|
|
|
|
Chybové odpovědi jsou JSON: `{"error": "<TypChyby>", "message": "...", "detail": "<text z upstreamu>"}`.
|
|
|
|
| HTTP | Kdy |
|
|
|------|-----|
|
|
| 400 | Chybí / prázdný audio soubor; **nepodporovaný nebo poškozený audio formát** (Deepgram/OpenAI vrátí 400/415/422) |
|
|
| 401 | Chybí `X-Deepgram-Api-Key` / `X-OpenAI-Api-Key`, **nebo upstream odmítl API klíč** (Deepgram/OpenAI 401/403) |
|
|
| 429 | Rate limit na Deepgram nebo OpenAI |
|
|
| 502 | Výpadek / neočekávaná chyba upstreamu (5xx, síťová chyba, timeout, neočekávaná struktura odpovědi) |
|
|
| 500 | Neočekávaná chyba serveru |
|
|
|
|
Mapování dělá `raise_for_upstream` v `app/errors.py`. Špatný typ souboru se pozná až
|
|
z odpovědi Deepgramu/OpenAI (bytes validují oni) a mapuje se na **400**, ne na 502.
|
|
Všechny chyby se logují (bez secrets), žádné tiché selhání.
|