ANLEITUNG

Eine Text-to-Speech-API in Python: speichern, streamen, wiederholen

Eine Text-to-Speech-API in der Cloud ist der kürzeste Weg, einem Python-Skript eine Stimme zu geben: kein Modell herunterladen, keine Grafikkarte, eine HTTP-Anfrage. Dieser Leitfaden zeigt die Sprach-API von SuperClonica aus Python mit der Bibliothek requests – von der ersten Datei bis zum Streaming langer Texte und zum Umgang mit Grenzen, wie es ein Produktivskript tun sollte.

Sie brauchen einen Schlüssel: Melden Sie sich mit Google oder GitHub bei SuperClonica an und erstellen Sie ihn im API-Bereich Ihres Arbeitsbereichs. Der kostenlose Tarif gibt eine Minute Audio pro Tag.

Eine Stimme wählen Oder die Engine lokal betreiben

Eine mp3 speichern

Legen Sie den Schlüssel in eine Umgebungsvariable und senden Sie den Text mit Stimme und Sprache:

import os, requests; KEY = os.environ["SUPERCLONICA_KEY"]; r = requests.post("https://superclonica.com/api/v1/speech", headers={"Authorization": "Bearer " + KEY}, json={"text": "Hallo aus Python!", "voice": "F1", "language": "de", "format": "mp3"}, timeout=120); r.raise_for_status(); open("hello.mp3", "wb").write(r.content)

Ohne "format" kommt die Antwort als Ogg Vorbis, die kleinste Datei; wav ist ebenfalls verfügbar. Eine Anfrage nimmt bis zu 20 000 Zeichen.

Einen langen Text streamen

Mit "stream": true sendet der Server das Audio, während es noch entsteht, sodass Sie es ab dem ersten Stück auf die Festplatte schreiben oder an einen Player geben können:

with requests.post("https://superclonica.com/api/v1/speech", headers={"Authorization": "Bearer " + KEY}, json={"text": long_text, "voice": "M2", "language": "de", "stream": True}, stream=True, timeout=120) as r: r.raise_for_status(); f = open("speech.ogg", "wb"); [f.write(chunk) for chunk in r.iter_content(8192)]; f.close()

In unseren Messungen kam der erste Ton unabhängig von der Textlänge ab 300 ms, und etwa 16 000 Zeichen wurden in 25,6 Sekunden vertont.

Stimmen und Grenzen

Listen Sie die Stimmen auf, die Ihr Schlüssel nutzen darf; jeder Eintrag hat eine id, einen Namen, eine Art (stock, own, bought oder catalog) und eine Sprache:

voices = requests.get("https://superclonica.com/api/v1/voices", headers={"Authorization": "Bearer " + KEY}, timeout=30).json()["items"]

Prüfen Sie vor einem großen Auftrag, was vom Tarif übrig ist:

usage = requests.get("https://superclonica.com/api/v1/usage", headers={"Authorization": "Bearer " + KEY}, timeout=30).json(); print(usage["plan"], usage["available_seconds"])

Fehler und Wiederholungen

Senden Sie mit jeder Anfrage einen Header Idempotency-Key, zum Beispiel einen Hash des Textes: Eine nach einem Timeout wiederholte Anfrage wartet dann auf dieselbe Aufgabe, statt den Text doppelt zu vertonen und zu zählen.

  • 429: Das 10-Minuten-Fenster des Tarifs ist aufgebraucht; warten Sie die Sekunden aus Retry-After und senden Sie erneut.
  • 503: Die Warteschlange ist voll; warten Sie Retry-After Sekunden und senden Sie mit demselben Schlüssel erneut.
  • 413: Der Text ist länger, als Ihr Tarif in einem Fenster erlaubt; teilen Sie ihn.
  • 401: Der Schlüssel fehlt, ist falsch oder gelöscht.
  • Ein fehlgeschlagener Text zählt nicht gegen den Tarif.