실시간 전사

실시간 전사는 지속 WebSocket 연결로 연속 오디오를 받고 오디오 항목별로 증분 텍스트와 최종 전사 결과를 반환합니다. 실시간 자막, 회의 기록, 통화 전사 및 음성 입력에 적합합니다. 전체 녹음 파일을 한 번에 업로드하려면 오디오 전사 인터페이스를 사용합니다.

gpt-live-transcribe는 낮은 지연의 증분 전사에 적합합니다. gpt-transcribe는 전체 음성 구간을 제출한 뒤 높은 정확도로 전사하는 데 적합하며 최종 이벤트에서 감지된 언어를 반환할 수 있습니다. 연결과 세션의 모델은 일치해야 합니다.

인증 및 연결

서버 애플리케이션은 WebSocket 핸드셰이크에서 Bearer API 키를 사용해야 합니다:

일반 브라우저의 WebSocket API는 Authorization Header를 임의로 설정할 수 없습니다. 따라서 프런트엔드 HTML, JavaScript 또는 클라이언트 패키지에 장기 API 키를 넣지 않습니다. 브라우저 제품은 신뢰할 수 있는 백엔드가 연결을 설정하거나 통제된 단기 자격 증명 메커니즘을 제공해야 합니다.

오디오 입력 요구 사항

이 문서의 입력 오디오는 PCM16 little-endian, 24 kHz, 모노를 사용하며 WAV 또는 다른 컨테이너 파일 헤더를 포함하지 않습니다. input_audio_buffer.append의 audio는 원시 PCM 바이트의 Base64 문자열입니다.

실시간 전송에는 작고 일정한 오디오 조각을 권장하며 단일 이벤트는 15 MiB를 초과하면 안 됩니다. 오디오 형식, 샘플링 주파수 또는 컨테이너 처리 오류는 전사 실패를 유발합니다.

세션 구성

session.update의 session.type은 항상 transcription입니다. 전사 구성은 session.audio.input.transcription에 있습니다:

noise_reduction.type=near_field는 헤드셋에, far_field는 회의실 또는 노트북 마이크에 적합합니다. null로 설정하면 잡음 제거를 끌 수 있습니다.

수동 제출 및 서버 VAD

• turn_detection: null: 클라이언트가 오디오를 보낸 뒤 input_audio_buffer.commit을 호출하며 업무 로직에서 분할을 명시적으로 제어할 때 적합합니다.
• 서버 VAD: 임계값, 음성 시작 전 패딩 및 무음 길이를 구성하고 서버가 음성 시작과 종료를 자동으로 식별합니다.

수동 모드에서는 빈 버퍼를 제출하지 않습니다. VAD가 활성화되면 speech_started와 speech_stopped에 따라 녹음 화면을 업데이트할 수 있지만 최종 전사는 completed 이벤트를 기준으로 해야 합니다.

연결 예시

다음 예시는 audio.pcm이 PCM16, 24 kHz, 모노 원시 오디오로 변환되었다고 가정합니다. 실제 실시간 애플리케이션에서는 전체 녹음을 한 번에 읽는 대신 작은 오디오 청크를 지속적으로 보내야 합니다.

import fs from 'node:fs';
import WebSocket from 'ws';

const ws = new WebSocket('wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID', {
  headers: {
    Authorization: 'Bearer your-api-key',
  },
});

ws.on('open', async () => {
  ws.send(JSON.stringify({
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "noise_reduction": { "type": "near_field" },
        "transcription": {
          "model": "MODEL_ID",
          "prompt": "중국어 고객 지원 통화",
          "keywords": ["AGTCloud", "API 게이트웨이"],
          "languages": ["zh-cn", "en"]
        },
        "turn_detection": null
      }
    }
  }
}));

  const audio = fs.createReadStream('audio.pcm', { highWaterMark: 4800 });
  for await (const chunk of audio) {
    ws.send(JSON.stringify({
      type: 'input_audio_buffer.append',
      audio: chunk.toString('base64'),
    }));
    await new Promise((resolve) => setTimeout(resolve, 100));
  }
  ws.send(JSON.stringify({ type: 'input_audio_buffer.commit' }));
});

ws.on('message', (message) => {
  const event = JSON.parse(message.toString());
  if (event.type.endsWith('.delta')) process.stdout.write(event.delta);
  if (event.type.endsWith('.completed')) console.log('\n', event.transcript);
});

이벤트 Reference

클라이언트는 세션 및 오디오 버퍼 이벤트로 입력을 제어하고 서버는 Item ID로 증분 텍스트, 최종 텍스트 및 오류를 연결합니다. 오디오 항목의 완료 순서가 다를 수 있으므로 item_id별로 텍스트를 집계해야 합니다.

{
  "event_id": "evt_session_001",
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "noise_reduction": {
          "type": "near_field"
        },
        "transcription": {
          "model": "MODEL_ID",
          "prompt": "중국어 고객 지원 통화",
          "keywords": [
            "AGTCloud",
            "API 게이트웨이"
          ],
          "languages": [
            "zh-cn",
            "en"
          ],
          "delay": "low"
        },
        "turn_detection": null
      }
    }
  }
}

오류 처리 및 복구

증분 텍스트는 후속 결과에서 수정될 수 있으므로 delta를 받았을 때 변경 불가능한 기록으로 저장하면 안 됩니다. completed의 transcript만 현재 오디오 항목의 최종 텍스트로 사용해야 합니다.