실시간 텍스트 음성 변환 v2

공개 Realtime TTS WebSocket v2 프로토콜로 음성을 스트리밍합니다.

Realtime TTS v2는 기존 클라이언트 호환성을 위해 유지됩니다. 새 통합은 상위 v3 페이지를 사용해야 합니다.

엔드포인트와 프로토콜

브랜드	엔드포인트
Fish Audio	`wss://realtime.fishaudio.org/v2/tts/live`

하위 프로토콜 realtime.tts.msgpack.v2를 요청하세요. 모든 애플리케이션 메시지는 JSON 텍스트가 아닌 MessagePack 바이너리 프레임입니다. 기존 /v1/tts/live 통합은 호환성을 위해 유지되며 신규 통합은 상위 v3 계약을 사용해야 합니다. 이 페이지는 v2 클라이언트 유지보수용입니다.

인증

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

브라우저에 장기 API 키를 전달하지 마세요. 신뢰할 수 있는 백엔드가 POST /v2/tts/browser-tickets를 통해 짧은 수명, 일회용, Origin 바인딩 티켓으로 교환해야 합니다. 브라우저는 첫 MessagePack 프레임으로 { event: 'auth', event_id, token: 'rtv2_ticket_...' }를 보냅니다. 자격 증명을 URL에 넣지 마세요.

흐름과 입력

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

기본 simple 모드에는 클라이언트 ID가 필요하지 않습니다. ready 후 { event: 'input', text }를 보내세요.

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

명시적 세그먼트, 멱등성 및 복구가 필요한 경우에만 start.mode='reliable'을 사용하세요. 이 모드에서는 event_id, request_id, text.sequence, flush.segment_id가 필수입니다.

클라이언트 이벤트는 auth, start, input, text, flush, stop, ping입니다. simple 모드에서는 보통 start와 input만 사용합니다.

클라이언트 이벤트 입력 매개변수

모든 이벤트는 MessagePack Map이며 알 수 없는 필드는 거부됩니다. reliable 모드의 event_id 요구 사항은 start부터 적용되고 그 이전의 auth에서는 생략할 수 있습니다.

이벤트	모드	필수 필드	선택 필드와 기본값	제약 및 동작
`auth`	모드 선택 전	`event`, `token`	`event_id`	`Authorization` 헤더가 없는 브라우저 티켓 인증에만 사용합니다.
`start`	simple, reliable	`event`, `request`	`mode: "simple"`, `event_id`, `request_id`, `retry_failed`	reliable에서는 `event_id`, `request_id`가 필수이며 재시도도 reliable 전용입니다.
`input`	simple	`event`, `text`	`event_id`, `commit: true`	빈 문자열은 허용되지 않으며 전체 버퍼는 최대 10,000자입니다.
`text`	reliable	`event`, `event_id`, `sequence`, `text`	없음	`sequence`는 양의 연속 번호이며 프레임당 최대 2,000자입니다.
`flush`	reliable	`event`, `event_id`, `segment_id`	없음	비어 있지 않은 버퍼를 확정하며 고유한 1～128자 `segment_id`를 사용합니다.
`stop`	reliable	`event`, `event_id`	없음	수락된 모든 세그먼트가 끝난 뒤 요청을 종료합니다.
`ping`	simple, reliable	`event`; reliable에서는 `event_id`도 필수	simple의 `event_id`, `timestamp`	서버가 `pong`으로 응답합니다.

PCM 응답에는 sample_rate, channels, bit_depth가 포함됩니다.

현재 형식은 mp3, wav, opus입니다. 공급자와 모델이 지원하는 경우 speed는 0.5～2, volume은 0～10, chunk_length는 50～1000입니다. 지원하지 않는 매개변수는 unsupported_parameter로 거부됩니다.

parameter_profile을 생략하면 기존 v2 동작이 유지되어 volume 범위는 0~~10이고 알 수 없거나 지원되지 않는 필드는 거부됩니다. parameter_profile: "product_v1"에서는 volume 범위가 -20~~20이며 stability, similarity, pitch, text_normalization, language, latency, emotion, instructions, optimize_instructions, chunk_length도 사용할 수 있습니다. 서버는 지원되는 값을 범위 안으로 제한하고 모델이 지원하지 않는 제어를 무시한 뒤 결과를 ready.effective_request로 반환합니다.

공개 voice_id는 모델과 호환되어야 합니다. 현재 공급자는 FishAudio, 모델은 fishaudio-s21pro-flash입니다. 연결하기 전에 GET /v2/tts/capabilities에서 Fish Audio가 지원하는 형식 및 매개변수를 확인하세요.

서버 이벤트는 authenticated, ready, input_ack, segment_accepted, audio, usage, segment_completed, request_status, warning, error, finish, pong입니다. simple 클라이언트는 ready, audio, error, finish만 처리하면 되고 reliable 클라이언트는 input_ack와 segment_completed를 기다립니다. audio.audio는 MessagePack 내부의 원시 바이트입니다.

안정적인 오류 코드는 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, internal_error입니다.