Verwandeln Sie Text in Sprache
Senden Sie Text über eine WebSocket-Verbindung und empfangen Sie Audio in Blöcken. Beginnen Sie mit einem vollständigen Beispiel, das eine abspielbare WAV-Datei speichert.
wss://api.starsg.ai/v1/realtime?model=tts-altair-v1-miniNeu bei Sprach-APIs? Beginnen Sie mit diesen vier Begriffen.
- WebSocket
- Eine Verbindung, die offen bleibt, sodass Ihr Programm und der Server Nachrichten in beide Richtungen austauschen können.
- Modell
- Die Engine, die die Aufgabe ausführt. Verwenden Sie zum Sprechen ein TTS-Modell und zum Transkribieren ein ASR-Modell. Kopieren Sie den genauen öffentlichen Ausweis.
- Stimme
- Die für die Synthese verwendete Stimme. Wählen Sie einen voice_id aus dem Katalog des ausgewählten Modells; Anerkennung braucht keine Stimme.
- API-Schlüssel
- Ihre Zugangsdaten, erstellt in der Konsole. Es wird in den Authorization-Header eingefügt, wenn die Verbindung geöffnet wird.
Ihre erste Verbindung
Wählen Sie Ihre Integrationsmethode und -umgebung und führen Sie dann die folgenden Schritte aus.
Bereiten Sie einen Ordner vor und installieren Sie die Bibliothek
Verwenden Sie Python 3.10 oder höher. Öffnen Sie ein Terminal in einem leeren Ordner und installieren Sie das offizielle OpenAI SDK. Die Verbindung zum Sprachgateway erfolgt über WebSocket. Das Beispiel wurde mit der folgenden Version getestet. Herunterladen ↗
python3 -m venv .venv .venv/bin/python -m pip install "openai[realtime]==3.35.1"
Legen Sie Ihren API-Schlüssel fest
Erstellen Sie einen Schlüssel in der Konsole und ersetzen Sie dann YOUR_API_KEY unten durch Ihren eigenen Schlüssel. Führen Sie dies im selben Terminal wie das Beispiel aus. Verwalten Sie API-Schlüssel ↗
export STARSG_API_KEY="YOUR_API_KEY"
Halten Sie Ihren Schlüssel geheim. Dies sind lokale/Server-Beispiele, kein Browsercode. Platzieren Sie keinen permanenten API-Schlüssel auf einer Webseite oder einem öffentlichen Repository. Durch das Ausführen des Beispiels wird ein abrechenbarer Modellaufruf durchgeführt.
Speichern Sie das Beispiel und führen Sie es aus
Kopieren Sie das vollständige Beispiel unten in eine neue Nur-Text-Datei mit dem Namen speech.py in diesem Ordner. Speichern Sie es und führen Sie dann diesen Befehl im selben Terminal aus.
.venv/bin/python speech.py
Wie Erfolg aussiehtDas Terminal gibt „Gespeichert:“ aus und erstellt eine Ausgabe.wav. Öffnen Sie es mit Ihrem Audioplayer. Um es erneut auszuführen, benennen Sie zunächst die Datei um oder entfernen Sie sie. das Beispiel wird es nicht überschreiben.
Vollständiges Beispiel
Kopieren Sie die gesamte Datei. Es stellt eine Verbindung her, konfiguriert die Sitzung, sendet eine Eingabe, wartet auf den Abschluss und schließt die Verbindung. Es wird nicht automatisch erneut versucht.
import asyncio
import base64
import json
import os
from pathlib import Path
import wave
from openai import AsyncOpenAI
API_KEY = os.environ["STARSG_API_KEY"]
BASE_URL = "https://api.starsg.ai/v1"
MODEL = "tts-altair-v1-mini"
SESSION = json.loads("{\"type\":\"realtime\",\"output_modalities\":[\"audio\"],\"audio\":{\"output\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000}}}}")
TEXT = "Hallo! Dies ist mein erstes Sprachsynthesebeispiel."
OUTPUT = Path("output.wav")
if OUTPUT.exists():
raise FileExistsError("output.wav exists; rename it before running again")
voice = os.environ.get("SPEECH_VOICE")
if voice:
SESSION["audio"]["output"]["voice"] = voice
async def main():
async with AsyncOpenAI(api_key=API_KEY, base_url=BASE_URL,
max_retries=0) as client:
async with client.realtime.connect(model=MODEL) as connection:
async def receive():
event = (await connection.recv()).model_dump()
if event["type"] == "error" or event["type"].endswith(".failed"):
raise RuntimeError(json.dumps(event.get("error", event), ensure_ascii=False))
return event
async def wait_for(kind):
while True:
event = await receive()
if event["type"] == kind:
return event
await wait_for("session.created")
await connection.session.update(session=SESSION)
await wait_for("session.updated")
await connection.conversation.item.create(item={
"type": "message", "role": "user",
"content": [{"type": "input_text", "text": TEXT}]
})
await connection.response.create()
audio = bytearray()
while True:
event = await receive()
if event["type"] == "response.output_audio.delta":
audio.extend(base64.b64decode(event["delta"], validate=True))
elif event["type"] == "response.done":
if event.get("response", {}).get("status") != "completed":
raise RuntimeError("Audio generation did not complete")
if not audio or len(audio) % 2:
raise ValueError("No valid PCM audio received")
with OUTPUT.open("xb") as target:
with wave.open(target, "wb") as wav:
wav.setparams((1, 2, 24000, 0, "NONE", "not compressed"))
wav.writeframes(audio)
print("Saved:", OUTPUT.resolve())
return
async def run():
await asyncio.wait_for(main(), timeout=90)
asyncio.run(run())
Das Beispiel verwendet eine öffentliche Modell-ID. Die Verfügbarkeit hängt von Ihrem Konto und Ihrer Umgebung ab. Wählen Sie ein Modell, das diese Echtzeitaufgabe unterstützt. Modelle ansehen ↗
Um eine Stimme auszuwählen, suchen Sie im Stimmenkatalog dieses Modells nach voice_id und stellen Sie SPEECH_VOICE in Ihrem Terminal ein, bevor Sie es ausführen. Lassen Sie es weg, um die Standardstimme zu verwenden. Ein Anzeigename wie „Alloy“ ist nicht voice_id. Ersetzen Sie VOICE_ID unten durch einen Wert aus diesem Katalog.
export SPEECH_VOICE="VOICE_ID"
Ereignisfluss
Jede Nachricht ist ein JSON-Ereignis. Senden bedeutet Ihr Programm → Server; Empfangen bedeutet Server → Ihr Programm. Warten Sie auf session.updated, bevor Sie Eingaben senden.
- Erhalten
session.createdDer Server hat eine Sitzung geöffnet. Sie können nun die Konfiguration senden.
- Schicken
session.updateLegen Sie die Aufgabe, das Audioformat und optional die Stimme fest.
- Erhalten
session.updatedDer Server hat die Konfiguration akzeptiert. Senden Sie nun die Eingabe.
- Schicken
conversation.item.createErstellen Sie eine Benutzernachricht mit content.type=input_text und content.text, die Ihren Text enthält.
- Schicken
response.createBitten Sie den Server, Audio für den Text zu generieren.
- Erhalten
response.output_audio.deltaDekodieren Sie das Deltafeld Base64 und sammeln Sie die PCM-Bytes der Reihe nach. Bei diesen Blöcken handelt es sich nicht um separate WAV-Dateien.
- Erhalten
response.doneÜberprüfen Sie, ob „response.status“ abgeschlossen ist, fügen Sie dann einen WAV-Header hinzu und speichern Sie das gesammelte Audio. Andere Status sind Fehler.
Überprüfen Sie die Meldung „session.update“.
{
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": [
"audio"
],
"audio": {
"output": {
"format": {
"type": "audio/pcm",
"rate": 24000
}
}
}
}
}Parameterreferenz
Namen mit Punkten zeigen an, wo ein Feld im JSON-Objekt hingehört. „Erforderlich“ unten gilt für den Arbeitsablauf in diesem Handbuch. Erweiterte Unterstützung und Einschränkungen hängen vom Modell ab.
Verbindung und Authentifizierung
modelstringErforderlichErforderlicher Abfrageparameter im WebSocket URL. Verwenden Sie die genaue öffentliche Modell-ID aus dem Echtzeitkatalog. Die Modelle ASR und TTS sind nicht austauschbar.
Beispiel/Einstellungtts-altair-v1-miniAuthorizationstringErforderlichVerbindungsheader: Bearer, ein Leerzeichen, dann Ihr API-Schlüssel. Verwenden Sie den Schlüssel für die Zielumgebung. Legen Sie es nicht in den URL.
Beispiel/EinstellungBearer <API_KEY>
Sitzung und Input
session.typestringErforderlichNutzen Sie Echtzeit für eine Text-to-Speech-Sitzung. Dies ist ein Synthese-Workflow, kein allgemeines Sprachagentengespräch.
Beispiel/Einstellung"realtime"session.output_modalitiesstring[]ErforderlichFordern Sie eine Audioausgabe zur Synthese an. Senden Sie dieses Array in session.update.
Beispiel/Einstellung["audio"]session.audio.output.formatobjectErforderlichAudiokonfiguration: Typ ist Audio/PCM, Rate ist 24000. In diesem Beispiel werden mono, vorzeichenbehaftete 16-Bit-Little-Endian-Samples verwendet: 48,000 Bytes pro Sekunde. WAV-Header werden nicht über den Socket gesendet.
Beispiel/Einstellung{"type":"audio/pcm","rate":24000}session.audio.output.voicestringOptionalOptional voice_id aus dem Sprachkatalog des ausgewählten Modells. Es ist auf das Modell beschränkt. Lassen Sie es für den Serverstandard weg; Verwenden Sie keinen Anzeigenamen des Anbieters. Stellen Sie es ein, bevor die Audioausgabe beginnt.
Durchsuchen Sie StimmenStandard / weggelassen Die Standardstimme des Modellsitem.content[].textstringErforderlichZu synthetisierender Text, innerhalb von „conversation.item.create“ → „Item“ → „Content“. Legen Sie den Typ des Inhaltselements auf input_text, item.type auf message und item.role auf user fest. Textgrenzen hängen vom Modell ab.
Optionale Sprachsteuerung
Beginnen Sie ohne diese Steuerelemente. Überprüfen Sie die output_controls des Modells, bevor Sie sie hinzufügen. Nicht unterstützte Lautstärke- oder Tonhöhenwerte verursachen einen Fehler; Sie werden nicht stillschweigend ignoriert. Sprach- und Geschwindigkeitssperre nach der ersten Audioausgabe; Lautstärke und Tonhöhe können später aktualisiert werden.
session.audio.output.speednumberOptionalE Sprechgeschwindigkeitsmultiplikator: 1.0 ist die normale Geschwindigkeit. Die akzeptierten Min/Max-Werte hängen vom Modell ab; Sehen Sie sich den Katalog an. Stellen Sie es vor der ersten Audioausgabe ein.
Beispiel/Einstellung1.0session.audio.output.options.volumenumber | nullOptionalPlattformerweiterung in Optionen: Verstärkungsmultiplikator, neutraler Wert 1.0. Der Protokollbereich ist 0 < Volumen ≤ 10, das Modell muss ihn jedoch unterstützen. Ausgelassen oder null verwendet den neutralen Wert; Nicht unterstützte Werte werden abgelehnt.
Standard / weggelassen1.0session.audio.output.options.pitchnumber | nullOptionalPlattformerweiterung in den Optionen: Tonhöhenverschiebung in Halbtönen, neutraler Wert 0. Der äußere Protokollbereich ist −24 bis 24; ein Modell erlaubt möglicherweise weniger. Nutzen Sie die angekündigten Limits. Weggelassen oder null verwendet neutrale Tonhöhe.
Standard / weggelassen0
Fehlerbehebung
Lesen Sie zuerst die zurückgegebene Fehlermeldung. Das Öffnen einer Verbindung oder das Eintreffen eines Audioblocks bedeutet nicht, dass die Anfrage erfolgreich abgeschlossen wurde.
Befehl nicht gefunden oder Modul fehlt
Installieren Sie die ausgewählte Laufzeit, öffnen Sie Ihr Terminal erneut und führen Sie die Setup-Befehle im Projektordner aus. Verwenden Sie für Python den oben gezeigten .venv-Interpreter. Installieren Sie den Websocket-Client, nicht das gleichnamige Websocket-Paket. Node.js-Beispiele verwenden das ws-Paket und eine .mjs-Datei.
401 / 403 oder fehlender Schlüssel API
Überprüfen Sie, ob die Umgebungsvariable in diesem Terminal festgelegt ist, YOUR_API_KEY ersetzt wurde und der Schlüssel zur Zielumgebung gehört. Bestätigen Sie den Modellzugriff und den Kontostatus. Halten Sie den Schlüssel aus Screenshots und Protokollen fern.
Handshake schlägt fehl, 404 / 503 oder Modell nicht gefunden
Überprüfen Sie den WSS-Hostnamen, den Port, den /v1/realtime-Pfad und die genaue öffentliche Modell-ID. Verwenden Sie den Echtzeitmodellkatalog für die Zielumgebung. Folgen Sie nicht einer Weiterleitung zu einem unsicheren HTTP URL. A 503 kann vom Dienstbetreiber verlangen, die Verfügbarkeit zu prüfen.
Kein Transkript, ungültiger Ton oder verstümmelte Wiedergabe
Überprüfen Sie 24 kHz, Mono, 16-Bit-Little-Endian-PCM und mindestens 100 ms Sprache. Verwenden Sie den Konvertierungsbefehl, anstatt die Datei umzubenennen. Die Erkennung sendet rohes PCM, nicht den WAV-Header. Zur Synthese dekodieren Sie Base64 und fügen Sie PCM-Blöcke zusammen, bevor Sie eine WAV-Datei erstellen.
invalid_value oder ein nicht unterstütztes Steuerelement
Entfernen Sie optionale Geschwindigkeits-, Lautstärke- und Tonhöheneinstellungen und überprüfen Sie dann output_controls für das ausgewählte Modell. Verwenden Sie voice_id oder numerische Grenzwerte eines anderen Modells nicht wieder. Ein abgelehntes session.update wendet diese Konfiguration nicht an.
Zeitüberschreitung oder Verbindung wird vorzeitig geschlossen
Die Beispiele stoppen nach 90 Sekunden. Versuchen Sie es mit einer kürzeren Eingabe und prüfen Sie den Netzwerkzugriff. Betrachten Sie ein teilweises Transkript oder eine teilweise Audioaufnahme nicht als Erfolg. Überprüfen Sie, ob die vorherige Anfrage ausgeführt wurde, bevor Sie es erneut versuchen, um doppelte Aufrufe zu vermeiden.
Die Datei „output.wav“ existiert bereits oder die Eingabedatei fehlt
Führen Sie das Skript aus dem Ordner aus, der Speech.py oder Speech.mjs enthält. Geben Sie dort input.wav (Python) oder input.pcm (Node.js) ein. Benennen Sie die vorherige Ausgabe.wav um, bevor Sie sie erneut generieren. Eine „Final:“-Zeile ist das Erkennungsergebnis; Es wird keine Audiodatei erstellt.
Protokollhintergrund: OpenAI WebSockets ↗