비동기 음성 텍스트 변환 | ElevenLabs Documentation

사용 가이드 · 음성 텍스트 변환 빠른 시작을 완료했다고 가정합니다.

개요

웹훅을 사용하면 음성 텍스트 변환 작업이 완료될 때 자동 알림을 받을 수 있어, 상태 업데이트를 위해 API를 계속 폴링할 필요가 없습니다. 이는 장시간 실행되는 변환 작업이나 대량의 오디오 파일을 처리할 때 특히 유용합니다.

변환이 완료되면 ElevenLabs는 트랜스크립트 텍스트, 언어 감지, 메타데이터를 포함한 변환 결과를 지정한 웹훅 URL로 POST 요청을 통해 전송합니다.

웹훅 사용하기

이 가이드는 API 키와 SDK를 설정했다고 가정합니다. 아직이라면 먼저 빠른 시작을 완료하세요.

웹훅 만들기 또는 수정하기

ElevenLabs 대시보드에서 개발자 > 웹훅으로 이동합니다. 웹훅 만들기를 클릭하거나 기존 웹훅을 수정합니다.

Transcription completed가 선택된 웹훅 만들기 대화상자 — 웹훅을 만들거나 수정할 때 Transcription completed를 선택하세요

다음과 같이 웹훅을 구성합니다.

이름: 웹훅을 설명하는 이름
콜백 URL: 공개적으로 접근 가능한 HTTPS 엔드포인트
웹훅 인증 방식: HMAC 또는 OAuth 중 하나입니다. 검증 메커니즘 구현은 클라이언트의 책임입니다. ElevenLabs는 검증에 사용할 수 있는 헤더를 전송하지만 강제하지는 않습니다.
이벤트: Transcription completed를 선택합니다.

웹훅 매개변수를 활성화하여 API 호출하기

음성 텍스트 변환 API를 호출할 때 webhook 매개변수를 true로 설정하면 해당 요청에 대한 웹훅 알림을 활성화할 수 있습니다.

from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)
def transcribe_with_webhook(audio_file):
  try:
    result = elevenlabs.speech_to_text.convert(
      file=audio_file,
      model_id="scribe_v2",
      webhook=True,
    )
    print(f"Transcription started: {result.request_id}")
    return result
  except Exception as e:
    print(f"Error starting transcription: {e}")
    raise e

웹훅 페이로드

변환이 완료되면 웹훅 엔드포인트는 변환 및 웹훅 데이터가 포함된 POST 요청을 받습니다.

{
  type: 'speech_to_text_transcription',
  data: {
    request_id: 'some-request-id-123',
    webhook_metadata: { ... }, // if provided in the convert request
    transcription: {
      "language_code": "en",
      "language_probability": 0.98,
      "text": "Hello world!",
      "words": [
        {
          "text": "Hello",
          "start": 0.0,
          "end": 0.5,
          "type": "word",
          "speaker_id": "speaker_1"
        },
        {
          "text": " ",
          "start": 0.5,
          "end": 0.5,
          "type": "spacing",
          "speaker_id": "speaker_1"
        },
        {
          "text": "world!",
          "start": 0.5,
          "end": 1.2,
          "type": "word",
          "speaker_id": "speaker_1"
        }
      ]
    }
  }
}

응답 구조에 대한 자세한 내용은 음성 텍스트 변환 API 레퍼런스를 참조하세요.

요청에 transcript_edit 지시가 포함된 경우, transcription 객체에는 수정된 텍스트가 담긴 edited_transcript 필드도 포함됩니다.

웹훅 엔드포인트 구현하기

수신 알림을 처리하는 웹훅 엔드포인트 구현 예시는 다음과 같습니다.

import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
import 'dotenv/config';
import express from 'express';
const elevenlabs = new ElevenLabsClient();
const app = express();
app.use(express.json());
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
app.post('/webhook/speech-to-text', (req, res) => {
  try {
    const signature = req.headers['elevenlabs-signature'];
    const payload = JSON.stringify(req.body);
    let event;
    try {
      // Verify the webhook signature.
      event = await elevenlabs.webhooks.constructEvent(payload, signature, WEBHOOK_SECRET);
    } catch (error) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
    if (event.type === 'speech_to_text.completed') {
      const { requestId, status, text, language_code } = event.data;
      console.log(`Transcription ${requestId} completed`);
      console.log(`Language: ${language_code}`);
      console.log(`Text: ${text}`);
      processTranscription(requestId, text, language_code);
    } else if (status === 'failed') {
      console.error(`Transcription ${requestId} failed`);
      handleTranscriptionError(requestId);
    }
    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});
async function processTranscription(requestId, text, language) {
  console.log('Processing completed transcription...');
}
async function handleTranscriptionError(requestId) {
  console.log('Handling transcription error...');
}
app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

보안 고려 사항

서명 검증

요청이 ElevenLabs에서 왔는지 확인하기 위해 항상 웹훅 서명을 검증하세요.

HTTPS 요구 사항

변환 데이터를 안전하게 전송하려면 웹훅 URL은 HTTPS를 사용해야 합니다.

속도 제한

악용을 방지하기 위해 웹훅 엔드포인트에 속도 제한을 구현하세요.

import rateLimit from "express-rate-limit";
const webhookLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
  message: "Too many webhook requests from this IP",
});
app.use("/webhook", webhookLimiter);

실패 응답

적절한 HTTP 상태 코드를 반환하세요.

200-299: 성공 - 웹훅이 성공적으로 처리됨
400-499: 클라이언트 오류 - 웹훅을 재시도하지 않음
500-599: 서버 오류 - 웹훅을 재시도함

웹훅 테스트하기

로컬 개발

로컬 테스트 시 ngrok과 같은 도구를 사용해 로컬 서버를 외부에 노출하세요.

ngrok http 3000

개발 중에는 제공된 HTTPS URL을 웹훅 엔드포인트로 사용하세요.

웹훅 테스트

변환 요청을 보내고 엔드포인트를 모니터링하여 웹훅 구현을 테스트할 수 있습니다.

async function testWebhook() {
  const audioFile = new File([audioBuffer], "test.mp3", { type: "audio/mp3" });
  const result = await elevenlabs.speechToText.convert({
    file: audioFile,
    modelId: "scribe_v2",
    webhook: true,
  });
  console.log("Test transcription started:", result.requestId);
}

다음 단계

서버 측 스트리밍

WebSocket 기반 스트리밍 API를 사용해 오디오를 실시간으로 변환합니다.

API 레퍼런스

전체 음성 텍스트 변환 API 레퍼런스 및 매개변수입니다.