# ElevenLabs Scribe (Speech-to-Text) — Endpoint-Referenz

Technische Referenz für den `/v1/speech-to-text` Endpoint (Scribe v1).
Wird vom `elevenlabs-api scribe`-Pfad konsumiert.

---

## Endpoint

```
POST https://api.elevenlabs.io/v1/speech-to-text
```

## Authentication

Header: `xi-api-key: <ELEVENLABS_API_KEY>`

Den Key niemals loggen oder im LLM-Kontext exponieren. Existenz-Check vor jedem Aufruf via `scripts/find_api_key.py`.

## Request Body (Multipart/Form-Data)

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `file` | binary | ja | Audio-Datei |
| `model_id` | string | ja | `scribe_v1` |

Beispiel mit `requests`:

```python
import requests

with open("audio.mp3", "rb") as f:
    response = requests.post(
        "https://api.elevenlabs.io/v1/speech-to-text",
        headers={"xi-api-key": api_key},
        data={"model_id": "scribe_v1"},
        files={"file": f},
    )
result = response.json()
```

## Response (JSON)

```json
{
  "text": "Transkribierter Text",
  "language_code": "de",
  "language_probability": 0.98,
  "words": [
    {"text": "Transkribierter", "start": 0.0, "end": 0.72, "type": "word"},
    {"text": " ", "start": 0.72, "end": 0.72, "type": "spacing"},
    {"text": "Text", "start": 0.72, "end": 1.05, "type": "word"}
  ]
}
```

| Feld | Beschreibung |
|---|---|
| `text` | Vollständiges Transkript |
| `language_code` | BCP-47 Sprachcode (z.B. `de`, `en`) |
| `language_probability` | Konfidenz der Spracherkennnung (0.0–1.0) |
| `words` | Array mit Wort-Timestamps |
| `words[].start` / `.end` | Zeitstempel in Sekunden |
| `words[].type` | `"word"`, `"spacing"`, `"audio_event"` |

## Audio-Format-Empfehlungen

Unterstützte Formate: mp3, wav, m4a, ogg, flac, aac, webm.
Empfohlen: mp3 oder wav für beste Erkennungsqualität.

Größen-Limit: laut ElevenLabs-Doku (vor Produktions-Einsatz verifizieren — Limit kann sich ändern).

## Umlaut-Hinweis

Deutsche Audio-Inputs erzeugen deutsche Transkripte mit echten Umlauten (ä, ö, ü, ß).
`start`/`end`-Werte im `words`-Array sind Sekunden als Float.

## Pflichten

- API-Key-Existenz-Check vor jedem Aufruf.
- Keinen Key-Wert ausgeben.
- `model_id` immer als `scribe_v1` übergeben.
