ElevenLabs 音声テキスト変換

Scribe v2 を使用して音声をテキストに変換します。90以上の言語、スピーカー分別、および単語レベルのタイムスタンプに対応しています。

セットアップ: インストールガイドを参照してください。JavaScript の場合、@elevenlabs/* パッケージのみを使用してください。

クイックスタート

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

with open("audio.mp3", "rb") as audio_file:
    result = client.speech_to_text.convert(file=audio_file, model_id="scribe_v2")

print(result.text)

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createReadStream } from "fs";

const client = new ElevenLabsClient();
const result = await client.speechToText.convert({
  file: createReadStream("audio.mp3"),
  modelId: "scribe_v2",
});
console.log(result.text);

cURL

curl -X POST "https://api.elevenlabs.io/v1/speech-to-text" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -F "file=@audio.mp3" -F "model_id=scribe_v2"

モデル

モデルID	説明	最適な用途
scribe_v2	最先端の精度、90以上の言語対応	バッチ文字起こし、字幕、長編オーディオ
scribe_v2_realtime	低遅延（約150ms）	ライブ文字起こし、音声エージェント

タイムスタンプ付き文字起こし

単語レベルのタイムスタンプには、タイプ分類とスピーカー識別が含まれます：

result = client.speech_to_text.convert(
    file=audio_file, model_id="scribe_v2", timestamps_granularity="word"
)

for word in result.words:
    print(f"{word.text}: {word.start}s - {word.end}s (type: {word.type})")

スピーカー分別

誰が何を言ったか識別します。モデルは各単語にスピーカーIDを付与し、会議、インタビュー、または複数のスピーカーを含むオーディオに有用です：

result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v2",
    diarize=True
)

for word in result.words:
    print(f"[{word.speaker_id}] {word.text}")

通話録音の場合、バッチAPI は分別されたスピーカーを diarize=true とともに detect_speaker_roles=true を設定することで agent と customer としてラベル付けできます。このオプションは use_multi_channel=true と互換性がありません。

curl -X POST "https://api.elevenlabs.io/v1/speech-to-text" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "file=@call.mp3" \
  -F "model_id=scribe_v2" \
  -F "diarize=true" \
  -F "detect_speaker_roles=true"

キーターム プロンプティング

モデルが誤認識しやすい特定の単語を認識させるのに役立ちます。製品名、技術用語、または変わったスペリング（最大100語まで）に対応：

result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v2",
    keyterms=["ElevenLabs", "Scribe", "API"]
)

言語検出

自動検出とオプションの言語ヒント：

result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v2",
    language_code="eng"  # ISO 639-1 または ISO 639-3 コード
)

print(f"Detected: {result.language_code} ({result.language_probability:.0%})")

サポートされるフォーマット

オーディオ: MP3、WAV、M4A、FLAC、OGG、WebM、AAC、AIFF、Opus ビデオ: MP4、AVI、MKV、MOV、WMV、FLV、WebM、MPEG、3GPP

制限: ファイルサイズ最大 3GB、再生時間 10 時間まで

レスポンス形式

{
  "text": "The full transcription text",
  "language_code": "eng",
  "language_probability": 0.98,
  "words": [
    {"text": "The", "start": 0.0, "end": 0.15, "type": "word", "speaker_id": "speaker_0"},
    {"text": " ", "start": 0.15, "end": 0.16, "type": "spacing", "speaker_id": "speaker_0"}
  ]
}

単語の種類：

• word - 実際に話された単語
• spacing - 単語間の空白（正確なタイミング用）
• audio_event - モデルが検出した非音声音（笑い声、拍手、音楽など）

エラーハンドリング

try:
    result = client.speech_to_text.convert(file=audio_file, model_id="scribe_v2")
except Exception as e:
    print(f"Transcription failed: {e}")

一般的なエラー：

• 401: 無効な API キー
• 422: 無効なパラメータ
• 429: レート制限超過

コスト追跡

request-id レスポンスヘッダーで使用状況を監視します：

response = client.speech_to_text.convert.with_raw_response(file=audio_file, model_id="scribe_v2")
result = response.parse()
print(f"Request ID: {response.headers.get('request-id')}")

リアルタイムストリーミング

ライブ文字起こしで超低遅延（約150ms）を実現するには、リアルタイム API を使用します。リアルタイム API は 2 つのタイプの文字起こしを生成します：

• 部分文字起こし: オーディオ処理時に頻繁に更新される暫定的な結果。ライブフィードバックに使用します（ユーザーが話している間にテキストを表示するなど）
• 確定文字起こし: 「確定」後の最終的で安定した結果。アプリケーションの信頼できるソースとして使用します

「確定」はモデルに現在のセグメントを最終化するよう指示します。手動で確定できます（ユーザーが一時停止したときなど）か、音声活動検知（VAD）を使用して沈黙時に自動確定します。

Python（サーバーサイド）

import asyncio
from elevenlabs import ElevenLabs

client = ElevenLabs()

async def transcribe_realtime():
    async with client.speech_to_text.realtime.connect(
        model_id="scribe_v2_realtime",
        include_timestamps=True,
        keyterms=["ElevenLabs", "Scribe"],
        no_verbatim=True,
    ) as connection:
        await connection.stream_url("https://example.com/audio.mp3")

        async for event in connection:
            if event.type == "partial_transcript":
                print(f"Partial: {event.text}")
            elif event.type == "committed_transcript":
                print(f"Final: {event.text}")

asyncio.run(transcribe_realtime())

JavaScript（React クライアントサイド）

import { useScribe, CommitStrategy } from "@elevenlabs/react";

function TranscriptionComponent() {
  const [transcript, setTranscript] = useState("");

  const scribe = useScribe({
    modelId: "scribe_v2_realtime",
    commitStrategy: CommitStrategy.VAD, // マイク入力の沈黙時に自動確定
    keyterms: ["ElevenLabs", "Scribe"],
    noVerbatim: true,
    onPartialTranscript: (data) => console.log("Partial:", data.text),
    onCommittedTranscript: (data) => setTranscript((prev) => prev + data.text),
  });

  const start = async () => {
    // バックエンドからトークンを取得（API キーをクライアントに露出させない）
    const { token } = await fetch("/scribe-token").then((r) => r.json());

    await scribe.connect({
      token,
      microphone: { echoCancellation: true, noiseSuppression: true },
    });
  };

  return <button onClick={start}>Start Recording</button>;
}

確定戦略

戦略	説明
Manual	準備ができたときに commit() を呼び出します。ファイル処理やオーディオセグメントを制御する場合に使用
VAD	音声活動検知が沈黙検出時に自動確定します。ライブマイク入力に使用

// React: フック上で commitStrategy を設定（マイク入力に推奨）
import { useScribe, CommitStrategy } from "@elevenlabs/react";

const scribe = useScribe({
  modelId: "scribe_v2_realtime",
  commitStrategy: CommitStrategy.VAD,
  keyterms: ["ElevenLabs", "Scribe"],
  noVerbatim: true,
  // オプション VAD チューニング：
  vadSilenceThresholdSecs: 1.5,
  vadThreshold: 0.4,
});

// JavaScript クライアント: connect 時に vad 設定を渡す
const connection = await client.speechToText.realtime.connect({
  modelId: "scribe_v2_realtime",
  keyterms: ["ElevenLabs", "Scribe"],
  noVerbatim: true,
  vad: {
    silenceThresholdSecs: 1.5,
    threshold: 0.4,
  },
});

イベントタイプ

イベント	説明
partial_transcript	ライブ暫定結果
committed_transcript	確定後の最終結果
committed_transcript_with_timestamps	タイミング付きの最終結果
error	エラー発生

完全なドキュメントはリアルタイムリファレンスを参照してください。

リファレンス

• インストールガイド
• 文字起こしオプション
• リアルタイムクライアントサイドストリーミング
• リアルタイムサーバーサイドストリーミング
• 確定戦略
• リアルタイムイベントリファレンス