탐색으로 건너뛰기

실시간 이벤트 레퍼런스

Realtime Speech to Text API에서 수신되는 이벤트 레퍼런스

레퍼런스 · Realtime Speech to Text WebSocket API에서 전송하고 수신하는 모든 이벤트를 나열합니다.

API 및 옵션에 관한 자세한 내용은 Realtime Speech to Text API API 레퍼런스를 참조하세요.

committed_transcript는 각 세그먼트에 대한 안정적인 최종 이벤트입니다. 공개 API는 별도의 final_transcript 이벤트를 내보내지 않습니다.

전송 이벤트

이벤트설명사용 시점
input_audio_chunk전사를 위한 오디오 데이터 전송오디오 스트리밍 중 지속적으로

Scribe v3 Live에서는 세션의 첫 번째 input_audio_chunk에 키텀 라이브러리를 포함할 수도 있습니다.

수신 이벤트

이벤트설명수신 시점
session_started연결을 확인하고 세션 구성을 반환합니다WebSocket 연결이 설정된 직후
partial_transcript진행 중인 세그먼트의 실시간 전사 업데이트입니다. 이후의 partial은 이전 항목을 대체합니다. diarize=true인 경우 speaker_id가 포함된 초안 words를 포함합니다(식별 전까지는 null). 화자 ID와 타임스탬프는 변경될 수 있으며, 정렬되지 않은 단어에는 타임스탬프가 없습니다. 또한 연결 유지용으로도 전송됩니다. 세그먼트에 커밋되지 않은 텍스트가 없으면 text는 비어 있고, 있으면 최신 partial을 반복합니다오디오 처리 중, 커밋되기 전. 구성된 경우 keepalive_interval_ms마다 약 한 번씩 연결 유지용으로도 전송됩니다
committed_transcript세그먼트의 확정된 전사입니다. 세그먼트의 안정적인 최종 텍스트이며 변경되지 않습니다. diarize=true인 경우 0부터 시작하는 segment_index를 포함하며 화자 분리로 인해 지연되지 않습니다커밋 후(수동 또는 VAD 트리거)
diarized_transcripttext, words, 그리고 committed transcript와 일치하는 segment_index가 포함된 화자 레이블 전사입니다. 확인되지 않은 화자의 speaker_id는 null입니다. 화자 분리를 참조하세요화자를 식별할 수 없는 경우에도 모든 committed transcript 후 커밋 순서대로 수신됩니다. diarize=true일 때만 수신됩니다
speakers_mergedfrom_speaker_id와 to_speaker_id가 동일 인물을 가리킴을 나타냅니다. partial 및 diarized transcript에서 이전의 모든 from_speaker_id 사용을 to_speaker_id로 바꾸고, 연속된 병합은 수신 순서대로 적용하세요. ID는 재사용되지 않습니다두 화자 ID가 동일 인물로 식별될 때. diarize=true일 때만 수신됩니다
committed_transcript_with_timestamps단어 수준 타임스탬프와 감지된 language_code가 포함된 committed transcript입니다committed transcript 후 전송됩니다. 쿼리 매개변수에 include_timestamps=true 또는 include_language_detection=true가 포함된 경우에만 수신됩니다
committed_transcript_entities문자 오프셋을 포함하여 committed transcript 세그먼트에서 감지된 엔터티입니다각 committed transcript 직후 전송됩니다. 쿼리 매개변수에 entity_detection이 포함된 경우에만 수신됩니다
redacted_transcript원본 committed 텍스트와 함께, 마스킹된 엔터티가 마커로 대체된 committed transcript 세그먼트입니다각 committed transcript 직후 전송됩니다. 쿼리 매개변수에 entity_redaction이 포함된 경우에만 수신됩니다
edited_transcript원본 committed 텍스트와 함께, 편집된 committed transcript 세그먼트 버전입니다각 committed transcript 직후 전송됩니다. 쿼리 매개변수에 transcript_edit가 포함된 경우에만 수신됩니다

언어 코드

쿼리 매개변수에서 include_language_detection=true를 설정하면 partial_transcript 및 committed_transcript_with_timestamps 이벤트의 음성 언어를 language_code로 받을 수 있습니다.

  • partial_transcript에서 language_code는 항상 존재하며, 진행 중인 세그먼트에 언어를 판별할 만큼 충분한 음성이 들어올 때까지 null입니다(약 4단어, 또는 중국어·일본어·태국어처럼 공백 없이 쓰는 언어의 경우 8자). 또한 동일한 언어가 연속된 partial에서 확인되어야 합니다. 한 단어처럼 매우 짧은 세그먼트는 계속 null일 수 있으며, 언어를 판별하기에 너무 짧은 partial은 연속 partial 수를 초기화합니다. 한 번 설정되면 새 언어가 연속된 partial에서 확인된 후에만 변경되므로, 한 번의 예외적인 partial로 값이 바뀌지 않습니다.
  • 문장 부호만 있는 경우처럼 발화 텍스트가 없는 partial의 language_code는 null입니다.
  • committed_transcript_with_timestamps의 language_code는 해당 세그먼트의 최종 결과입니다. 마지막 partial과 다르면 committed 값을 사용하세요. 이는 committed_transcript 후에 전송되므로, 도착할 때까지는 partial 값을 표시하세요.
  • 연결 시 language_code 또는 secondary_languages를 전달하면 해당 언어 내에서 모델이 인식한 언어를 사용합니다. 힌트가 없으면 전사 텍스트에서 감지합니다.
  • include_language_detection=true 없이 사용하면 partial_transcript 이벤트에 language_code 필드가 없습니다.

오류 처리

오류가 발생하면 WebSocket 연결이 닫히기 전에 오류 메시지가 반환됩니다.

오류 유형설명
auth_error요청을 인증하는 동안 오류가 발생했습니다. API 키를 다시 확인하세요
quota_exceeded사용 할당량을 초과했습니다
transcriber_error오디오를 전사하는 동안 오류가 발생했습니다.
input_error오디오 청크를 처리하는 동안 오류가 발생했습니다. 입력 형식 또는 매개변수가 잘못되었을 수 있습니다
invalid_request연결 매개변수가 거부되었습니다. API 레퍼런스에서 쿼리 매개변수를 확인하세요
error일반적인 서버 오류입니다. 연결이 닫히기 전에 엔터티 마스킹에 실패한 경우에도 전송됩니다
commit_throttled짧은 시간에 너무 많은 커밋 요청이 발생하여 커밋이 제한되었습니다
unaccepted_termsScribe를 사용하기 위한 서비스 약관에 동의하지 않았습니다. ElevenLabs 대시보드에서 이용 약관을 검토하고 동의하세요
rate_limited요청 빈도가 제한되었습니다. 짧은 시간 동안 요청 수를 줄이세요
queue_overflow처리 대기열이 가득 찼습니다. 짧은 시간 동안 요청 수를 줄이세요
resource_exhausted서버 리소스가 한계에 도달했습니다. 나중에 다시 시도하세요
session_time_limit_exceeded최대 세션 시간에 도달했습니다. 새 세션을 시작하거나 구독을 업그레이드하세요
chunk_size_exceeded오디오 청크 크기가 너무 큽니다. 청크 크기를 줄이세요
insufficient_audio_activity연결을 유지하기에 충분한 오디오 활동을 전송하지 않았습니다