非同期スピーチtoテキスト | ElevenLabs Documentation

ハウツーガイド · スピーチtoテキストのクイックスタートを完了していることを前提としています。

概要

Webhookを使用すると、スピーチtoテキストの文字起こしタスクが完了した際に自動通知を受け取れるため、ステータス更新のためにAPIを継続的にポーリングする必要がなくなります。これは、長時間実行される文字起こしジョブや、大量のオーディオファイルを処理する場合に特に便利です。

文字起こしが完了すると、ElevenLabsは指定したWebhook URLにPOSTリクエストを送信します。リクエストには、文字起こしテキスト、言語検出、メタデータなどの文字起こし結果が含まれます。

Webhookの使用

このガイドでは、APIキーとSDKを設定済みであることを前提としています。未完了の場合は、先にクイックスタートを完了してください。

Webhookを作成または編集する

ElevenLabsダッシュボードで、 開発者 > Webhookに移動します。 Webhookを作成をクリックするか、既存のWebhookを編集します。

「文字起こし完了」が選択されたWebhook作成ダイアログ — Webhookの作成または編集時に「文字起こし完了」を選択します

Webhookを以下のように設定します。

名前：Webhookを説明する名前
コールバックURL：公開アクセス可能なHTTPSエンドポイント
Webhook認証方式：HMACまたはOAuth。検証メカニズムの実装はクライアント側で行います。ElevenLabsは検証に使用できるヘッダーを送信しますが、強制はしません。
イベント：文字起こし完了を選択します。

Webhookパラメータを有効にしてAPIを呼び出す

スピーチtoテキストAPIを呼び出す際は、特定のリクエストに対するWebhook通知を有効にするため、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

Webhookペイロード

文字起こしが完了すると、Webhookエンドポイントは文字起こしデータとWebhookデータを含む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"
        }
      ]
    }
  }
}

レスポンス構造の詳細については、スピーチtoテキストAPIリファレンスを参照してください。

リクエストにtranscript_edit指示が含まれていた場合、transcriptionオブジェクトには編集済みテキストを含むedited_transcriptフィールドも含まれます。

文字起こしに失敗した場合、エンドポイントは代わりにwebhook_errorイベントを受け取ります。このイベントにはdataオブジェクトはありません。トップレベルのrequest_id（リクエストの受付時に返されるIDと同じ）、error_message、およびリクエストのwebhook_metadataが含まれます。

Webhookエンドポイントの実装

受信通知を処理するWebhookエンドポイントの実装例を以下に示します。

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";
import express from "express";
const elevenlabs = new ElevenLabsClient();
const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
// The raw body is required: verification runs over the exact bytes sent.
app.post("/webhook/speech-to-text", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.headers["elevenlabs-signature"];
  let event;
  try {
    event = await elevenlabs.webhooks.constructEvent(
      req.body.toString(),
      signature,
      WEBHOOK_SECRET
    );
  } catch (error) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  if (event.type === "speech_to_text_transcription") {
    const { request_id, transcription } = event.data;
    console.log(`Transcription ${request_id} completed`);
    console.log(`Language: ${transcription.language_code}`);
    console.log(`Text: ${transcription.text}`);
    processTranscription(request_id, transcription);
  } else if (event.type === "webhook_error") {
    console.error(`Transcription ${event.request_id} failed: ${event.error_message}`);
    handleTranscriptionError(event.request_id, event.webhook_metadata, event.error_message);
  }
  res.status(200).json({ received: true });
});
async function processTranscription(requestId, transcription) {
  console.log("Processing completed transcription...");
}
async function handleTranscriptionError(requestId, webhookMetadata, errorMessage) {
  console.log("Handling transcription error...");
}
app.listen(3000, () => {
  console.log("Webhook server listening on port 3000");
});

セキュリティに関する考慮事項

署名の検証

リクエストがElevenLabsから送信されたことを確認するため、Webhook署名を必ず検証してください。

HTTPSの要件

文字起こしデータを安全に送信するため、Webhook URLにはHTTPSを使用する必要があります。

レート制限

不正利用を防ぐため、Webhookエンドポイントにレート制限を実装します。

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);

失敗時のレスポンス

Webhookを受信確認するには、2xxステータスコードを返します。

デフォルトでは、スピーチtoテキストの文字起こしWebhookは1回だけ配信されます。2xx以外のレスポンスはすべて配信失敗として扱われ、失敗が繰り返されるとWebhookは自動的に無効化されます。

Webhookで再試行を有効にすると、失敗した配信（5xx、408、429、または接続エラー）は、前回の試行からおよそ30秒、2分、8分、30分、30分後に、最大5回再試行されます。その他の4xxレスポンスは再試行されません。同じイベントに対するすべての試行には同じElevenLabs-Webhook-Delivery-Idヘッダーが付与されるため、ハンドラーで重複を無視できます。

enable_loggingをfalse（保持期間ゼロモード）に設定したリクエストは、再試行が有効な場合、前回の試行から5秒後と30秒後に最大2回、短時間で再試行されます。文字起こしは保存されません。

それでも配信に失敗した場合は、リクエストの受付時に返されたtranscription_idを使用して、文字起こしを取得してください。enable_loggingをfalseに設定したリクエストの文字起こしは保存されません。

Webhookのテスト

ローカル開発

ローカルでテストするには、ngrokなどのツールを使用してローカルサーバーを公開します。

ngrok http 3000

開発中は、提供されたHTTPS URLをWebhookエンドポイントとして使用します。

Webhookのテスト

文字起こしリクエストを送信してエンドポイントを監視することで、Webhook実装をテストできます。

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リファレンス

スピーチtoテキストAPIの完全なリファレンスとパラメータ。