# Sprechpult von Cleverfritz: Anleitung für KIs

Das Sprechpult macht aus deutschem Text eine Audiodatei. Es nutzt dafür Google Cloud Text-to-Speech auf Rechnung des
Inhabers (Nico, Cleverfritz). Du arbeitest über eine Schnittstelle (HTTP, JSON), nicht über die Oberfläche.

Adresse: `https://sprechpult.cleverfritz.de`

## Regeln

- Du brauchst einen Zugangscode. Den erstellt der Inhaber für dich im Sprechpult unter „Zugang für KIs“. Er beginnt mit
  `sp_`. Gib ihn nie weiter, schreib ihn in keine Antwort, kein Protokoll und keine Datei, die andere lesen.
- Jede Anfrage kostet Zeichen aus dem Kontingent des Inhabers. Erzeuge nur, was gebraucht wird, und nicht dasselbe
  mehrfach. Dein Zugang hat eine Tagesgrenze (Zeichen je Tag, Tag nach Weltzeit) und höchstens 20 Anfragen je Minute.
- Nur Deutsch (`de-DE`).
- Du siehst nur deine eigenen Aufnahmen. Der Inhaber sieht alle, auch deine, mit deinem Namen daran.
- Kein Text mit personenbezogenen Daten Dritter, es sei denn, der Inhaber hat es ausdrücklich beauftragt: Der Text
  geht zum Vorlesen an Google.

## Anmelden

Jede Anfrage trägt den Kopf `Authorization: Bearer <Zugangscode>`.

## Sprache erzeugen

`POST https://sprechpult.cleverfritz.de/api/v1/sprechen` mit `Content-Type: application/json`

| Feld | Pflicht | Bedeutung |
|---|---|---|
| `text` | eines von beiden | reiner Text. Lange Texte werden an Satzgrenzen geteilt und wieder zusammengesetzt. |
| `ssml` | eines von beiden | ein SSML-Dokument (`<speak>…</speak>`, höchstens 5000 Bytes) oder eine Liste davon |
| `stimme` | nein | Name einer Stimme, siehe unten. Ohne Angabe die Standardstimme des Sprechpults. |
| `format` | nein | `mp3` (Standard), `wav` oder `ogg`. Mehrere Abschnitte gehen nur als `mp3` oder `wav`. |
| `tempo` | nein | 0.25 bis 2, normal ist 1 |
| `tonhoehe` | nein | −20 bis 20 Halbtöne, normal ist 0. Chirp 3: HD und Studio kennen das nicht. |
| `lautstaerke` | nein | −96 bis 16 dB, normal ist 0 |
| `titel` | nein | Name der Aufnahme, wird Teil des Dateinamens |
| `modell`, `stil` | nein | nur für Gemini-TTS, siehe unten |

Antwort (200):

```json
{ "datei": "2026-11-18_101500_begruessung.mp3", "url": "https://sprechpult.cleverfritz.de/ausgabe/2026-11-18_101500_begruessung.mp3",
  "stimme": "de-DE-Chirp3-HD-Sulafat", "format": "MP3", "zeichen": 61, "abschnitte": 1, "groesse": 20160,
  "sekunden": null, "heute_verbraucht": 61, "tagesgrenze": 20000 }
```

Die Audiodatei holst du mit demselben Kopf `Authorization` unter `url`.

Beispiel:

```bash
curl -s -X POST "https://sprechpult.cleverfritz.de/api/v1/sprechen" \
  -H "Authorization: Bearer $SPRECHPULT_CODE" -H "Content-Type: application/json" \
  -d '{"text":"Guten Morgen Chef. Deine neue Website ist fertig.","titel":"Begrüßung"}'
```

## Weitere Adressen

- `GET /api/v1/stimmen`: die deutschen Stimmen (`name`, `geschlecht`), die Standardstimme und ob Gemini-TTS
  eingerichtet ist (`gemini`).
- `GET /api/v1/aufnahmen`: deine bisherigen Aufnahmen mit `url`.
- `GET /api/v1/anleitung`: dieser Text.

## So soll eine Stelle klingen (SSML)

Schick statt `text` ein SSML-Dokument. `&`, `<` und `>` im Text als `&amp;`, `&lt;`, `&gt;` schreiben.

| Wirkung | SSML |
|---|---|
| Pause | `<break time="500ms"/>` |
| lauter, leiser | `<prosody volume="loud">…</prosody>`, Werte `x-soft`, `soft`, `loud`, `x-loud` |
| schneller, langsamer | `<prosody rate="slow">…</prosody>`, Werte `x-slow`, `slow`, `fast`, `x-fast` |
| höher, tiefer | `<prosody pitch="+2st">…</prosody>` |
| betonen | `<emphasis level="strong">…</emphasis>`, Werte `strong`, `moderate`, `reduced` |
| Frage | Satz mit `?` beenden; das letzte Wort zusätzlich in `<prosody pitch="+3st">…</prosody>` |
| Datum, Uhrzeit | `<say-as interpret-as="date" format="dmy">24.11.2026</say-as>`, `<say-as interpret-as="time" format="hms24">14:30</say-as>` |
| Telefonnummer, buchstabieren | `<say-as interpret-as="telephone">…</say-as>`, `<say-as interpret-as="verbatim">…</say-as>` |
| anders aussprechen | `<sub alias="Gesellschaft mit beschränkter Haftung">GmbH</sub>` |
| Absatz | `<p>…</p>` |

Beispiel: `<speak><p>Hallo Chef.<break time="500ms"/> Deine Website ist <emphasis level="strong">fertig</emphasis>.</p></speak>`

Was die Stimmen können:

| Stimmen | Kennzeichen im Namen | Einschränkung |
|---|---|---|
| Chirp 3: HD | `-Chirp3-HD-` | keine Betonung (`emphasis`), kein Regler `tonhoehe` |
| Neural2, WaveNet, Standard | `-Neural2-`, `-Wavenet-`, `-Standard-` | setzen alles um |
| Studio | `-Studio-` | keine Betonung, kein `pitch` |
| Chirp HD | `-Chirp-HD-` | nur reiner Text |

Was eine Stimme nicht kennt, lässt Google stillschweigend weg; der Text wird trotzdem gesprochen.

## Gemini-TTS

Geht nur, wenn `GET /api/v1/stimmen` `"gemini": true` meldet. Dann `modell` setzen (zum Beispiel
`gemini-2.5-flash-tts`), als `stimme` einen der Namen wie `Kore`, `Sulafat` oder `Charon` und in `stil` den Tonfall in
Worten („Sprich freundlich und ruhig“). Kein SSML, dafür Marken im Text: `[short pause]`, `[medium pause]`,
`[long pause]`, `[whispering]`, `[shouting]`, `[extremely fast]`, `[sigh]`, `[laughing]`, `[uhm]`. Gemini-TTS hat kein
Freikontingent und kostet vom ersten Zeichen an.

## Fehler

Fehler kommen als JSON `{ "fehler": "…" }`, bei Ablehnung durch Google zusätzlich mit `"google": "…"`.

| Status | Bedeutung | Was du tust |
|---|---|---|
| 400 | Anfrage unvollständig oder von Google abgelehnt | Meldung lesen, Anfrage korrigieren |
| 401 | Zugangscode fehlt oder ist gesperrt | nicht wiederholen, dem Inhaber melden |
| 409 | im Sprechpult fehlt der Google-Schlüssel | dem Inhaber melden |
| 429 | Tagesgrenze erreicht oder mehr als 20 Anfragen je Minute | warten, nicht in einer Schleife wiederholen |
| 5xx | Sprechpult oder Google gestört | einmal nach einer Minute wiederholen, dann dem Inhaber melden |
