Echtzeit-Text-to-Speech v2

Realtime TTS v2 bleibt für bestehende Clients erhalten. Neue Integrationen sollten die übergeordnete v3-Seite verwenden.

Endpunkte und Protokoll

Fordern Sie das Subprotokoll realtime.tts.msgpack.v2 an. Alle Anwendungsnachrichten sind MessagePack-Binärframes, keine JSON-Textframes. Vorhandene /v1/tts/live-Integrationen bleiben kompatibel; neue Integrationen verwenden den übergeordneten v3-Vertrag. Diese Seite dient nur der Pflege von v2-Clients.

Authentifizierung

Authorization: Bearer API_KEY
Sec-WebSocket-Protocol: realtime.tts.msgpack.v2

Geben Sie Browsern keinen langlebigen API-Schlüssel. Ein vertrauenswürdiges Backend tauscht ihn über POST /v2/tts/browser-tickets gegen ein kurzlebiges, einmaliges und Origin-gebundenes Ticket aus. Der Browser sendet { event: 'auth', event_id, token: 'rtv2_ticket_...' } als ersten MessagePack-Frame. Zugangsdaten dürfen nie in URL-Parametern stehen.

Ablauf und Eingabe

connect → authenticated → start → ready → input → audio → finish

Im standardmäßigen simple-Modus sind keine Client-IDs erforderlich. Senden Sie nach ready { event: 'input', text }:

{
  event: 'start',
  request: {
    voice_id: 'PUBLIC_VOICE_UUID',
    model: 'fishaudio-s21pro-flash',
    format: 'mp3',
    speed: 1,
    volume: 0,
    language: 'de',
    chunk_length: 200,
    latency: 'normal'
  }
}

Verwenden Sie start.mode='reliable' nur für explizite Segmente, Idempotenz und Wiederherstellung. Dann sind event_id, request_id, text.sequence und flush.segment_id erforderlich.

Client-Ereignisse sind auth, start, input, text, flush, stop und ping. Der simple-Modus verwendet normalerweise nur start und input.

Parameter der Client-Ereignisse

Jedes Ereignis ist eine MessagePack-Map; unbekannte Felder werden abgelehnt. Im reliable-Modus gilt die event_id-Pflicht ab start; das vorherige auth darf sie auslassen.

PCM-Antworten enthalten sample_rate, channels und bit_depth.

Die aktuellen Formate sind mp3, wav, opus. speed liegt zwischen 0.5 und 2, volume zwischen 0 und 10, chunk_length zwischen 50 und 1000, sofern der Anbieter und das Modell sie unterstützen. Nicht unterstützte Parameter werden mit unsupported_parameter abgelehnt.

Ohne parameter_profile bleibt v2 unverändert: volume liegt zwischen 0 und 10, unbekannte oder nicht unterstützte Felder werden abgelehnt. Mit parameter_profile: "product_v1" verwendet volume den Bereich -20 bis 20; zusätzlich stehen stability, similarity, pitch, text_normalization, language, latency, emotion, instructions, optimize_instructions und chunk_length zur Verfügung. Der Server begrenzt unterstützte Werte, ignoriert vom Modell nicht unterstützte Steuerelemente und meldet das Ergebnis in ready.effective_request.

Die öffentliche voice_id muss zum Modell passen. Aktuelle Anbieter sind FishAudio, die Modelle sind fishaudio-s21pro-flash. Prüfen Sie vor der Verbindung mit GET /v2/tts/capabilities, welche Formate und Parameter Fish Audio unterstützt.

Der Server sendet authenticated, ready, input_ack, segment_accepted, audio, usage, segment_completed, request_status, warning, error, finish und pong. Simple-Clients müssen nur ready, audio, error und finish verarbeiten. Reliable-Clients warten auf input_ack und segment_completed. audio.audio enthält rohe Bytes im MessagePack-Frame.

Stabile Fehlercodes umfassen authentication_failed, authentication_required, already_authenticated, permission_denied, invalid_message, invalid_messagepack, invalid_state, idempotency_conflict, empty_segment, segment_too_large, session_limit_exceeded, quota_exceeded, client_backpressure, unsupported_parameter, voice_not_found, model_not_found, provider_unavailable, provider_timeout, generation_failed, billing_failed, connection_closed und internal_error.