Texto a voz en tiempo real v2
Transmite voz con el protocolo público WebSocket Realtime TTS v2.
Realtime TTS v2 se conserva para los clientes existentes. Las integraciones nuevas deben usar la página v3 superior.
Endpoints y protocolo
| Marca | Endpoint |
|---|---|
| Fish Audio | wss://realtime.fishaudio.org/v2/tts/live |
Solicita el subprotocolo realtime.tts.msgpack.v2. Todos los mensajes de aplicación son tramas binarias MessagePack, no texto JSON. Las integraciones existentes con /v1/tts/live siguen disponibles por compatibilidad; las nuevas deben usar el contrato v3 superior. Esta página solo sirve para mantener clientes v2.
Autenticación
Authorization: Bearer API_KEY
Sec-WebSocket-Protocol: realtime.tts.msgpack.v2No entregues una clave API duradera al navegador. Un backend de confianza debe cambiarla mediante POST /v2/tts/browser-tickets por un ticket breve, de un solo uso y vinculado al Origin. El navegador envía { event: 'auth', event_id, token: 'rtv2_ticket_...' } como primera trama MessagePack. Nunca incluyas credenciales en la URL.
Flujo y parámetros
connect → authenticated → start → ready → input → audio → finishEl modo simple predeterminado no requiere identificadores del cliente. Después de ready, envía { event: 'input', text }:
{
event: 'start',
request: {
voice_id: 'PUBLIC_VOICE_UUID',
model: 'fishaudio-s21pro-flash',
format: 'mp3',
speed: 1,
volume: 0,
language: 'es',
chunk_length: 200,
latency: 'normal'
}
}Usa start.mode='reliable' solo para segmentación explícita, idempotencia y recuperación. En ese modo se requieren event_id, request_id, text.sequence y flush.segment_id.
Los eventos del cliente son auth, start, input, text, flush, stop y ping. El modo simple normalmente solo usa start e input.
Parámetros de eventos del cliente
Cada evento es un mapa MessagePack y se rechazan los campos desconocidos. En modo reliable, event_id es obligatorio desde start; el auth anterior puede omitirlo.
| Evento | Modo | Campos obligatorios | Opcionales y valores predeterminados | Restricciones y comportamiento |
|---|---|---|---|---|
auth | Antes del modo | event, token | event_id | Solo para un ticket de navegador sin cabecera Authorization. |
start | simple, reliable | event, request | mode: "simple", event_id, request_id, retry_failed | Reliable exige event_id y request_id; el reintento es exclusivo de reliable. |
input | simple | event, text | event_id, commit: true | Texto no vacío; máximo 10.000 caracteres acumulados. |
text | reliable | event, event_id, sequence, text | Ninguno | sequence positiva y consecutiva; máximo 2.000 caracteres por trama. |
flush | reliable | event, event_id, segment_id | Ninguno | Confirma un búfer no vacío; segment_id único de 1–128 caracteres. |
stop | reliable | event, event_id | Ninguno | Finaliza después de todos los segmentos aceptados. |
ping | simple, reliable | event; en reliable también event_id | event_id en simple, timestamp | El servidor responde con pong. |
Las respuestas PCM incluyen sample_rate, channels y bit_depth.
Los formatos actuales son mp3, wav, opus. speed va de 0.5 a 2, volume de 0 a 10 y chunk_length de 50 a 1000 cuando el proveedor y el modelo los admiten. Los parámetros no compatibles devuelven unsupported_parameter.
Si se omite parameter_profile, v2 conserva su comportamiento anterior: volume va de 0 a 10 y los campos desconocidos o no compatibles se rechazan. Con parameter_profile: "product_v1", volume va de -20 a 20 y también se admiten stability, similarity, pitch, text_normalization, language, latency, emotion, instructions, optimize_instructions y chunk_length. El servidor limita los valores compatibles, ignora los controles que el modelo no admite y devuelve el resultado en ready.effective_request.
La voice_id pública debe ser compatible con el modelo. Los proveedores actuales son FishAudio y los modelos son fishaudio-s21pro-flash. Consulta GET /v2/tts/capabilities antes de conectarte para conocer los formatos y parámetros admitidos por Fish Audio.
El servidor emite authenticated, ready, input_ack, segment_accepted, audio, usage, segment_completed, request_status, warning, error, finish y pong. Los clientes simples solo necesitan procesar ready, audio, error y finish; los clientes reliable esperan input_ack y segment_completed. audio.audio contiene bytes sin Base64 dentro de MessagePack.
Los códigos de error estables incluyen 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 e internal_error.