Texto para fala em tempo real v2

Realtime TTS v2 é mantido para clientes existentes. Novas integrações devem usar a página v3 superior.

Endpoints e protocolo

Solicite o subprotocolo realtime.tts.msgpack.v2. Todas as mensagens da aplicação são frames binários MessagePack, não texto JSON. As integrações /v1/tts/live existentes continuam disponíveis por compatibilidade; novas integrações devem usar o contrato v3 superior. Esta página serve apenas para manter clientes v2.

Autenticação

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

Não entregue uma chave API duradoura ao navegador. Um backend confiável deve trocá-la em POST /v2/tts/browser-tickets por um ticket curto, de uso único e vinculado ao Origin. O navegador envia { event: 'auth', event_id, token: 'rtv2_ticket_...' } como o primeiro frame MessagePack. Nunca coloque credenciais na URL.

Fluxo e parâmetros

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

O modo simple padrão não exige IDs do cliente. Após ready, envie { event: 'input', text }:

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

Use start.mode='reliable' apenas para segmentação explícita, idempotência e recuperação. Nesse modo, event_id, request_id, text.sequence e flush.segment_id são obrigatórios.

Os eventos do cliente são auth, start, input, text, flush, stop e ping. O modo simple normalmente usa apenas start e input.

Parâmetros dos eventos do cliente

Cada evento é um mapa MessagePack e campos desconhecidos são rejeitados. No modo reliable, event_id é obrigatório a partir de start; o auth anterior pode omiti-lo.

As respostas PCM incluem sample_rate, channels e bit_depth.

Os formatos atuais são mp3, wav, opus. speed varia de 0.5 a 2, volume de 0 a 10 e chunk_length de 50 a 1000 quando o provedor e o modelo oferecem suporte. Parâmetros incompatíveis retornam unsupported_parameter.

Sem parameter_profile, o v2 mantém o comportamento anterior: volume varia de 0 a 10 e campos desconhecidos ou sem suporte são rejeitados. Com parameter_profile: "product_v1", volume varia de -20 a 20 e também ficam disponíveis stability, similarity, pitch, text_normalization, language, latency, emotion, instructions, optimize_instructions e chunk_length. O servidor limita valores compatíveis, ignora controles sem suporte no modelo e retorna o resultado em ready.effective_request.

A voice_id pública deve ser compatível com o modelo. Os provedores atuais são FishAudio e os modelos são fishaudio-s21pro-flash. Consulte GET /v2/tts/capabilities antes de conectar para conhecer os formatos e parâmetros aceitos pelo Fish Audio.

O servidor envia authenticated, ready, input_ack, segment_accepted, audio, usage, segment_completed, request_status, warning, error, finish e pong. Clientes simple só precisam processar ready, audio, error e finish; clientes reliable aguardam input_ack e segment_completed. audio.audio contém bytes brutos no MessagePack.

Os códigos de erro estáveis incluem 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.