AI Skills
speech-to-text

speech-to-text

熱門

使用 ElevenLabs Scribe v2 將音訊轉錄為文字。適用於將音訊/影片轉換為文字、產生字幕、轉錄會議或處理語音內容。

384星標
50分支
更新於 2026/7/15
獲取技能源代碼

相關技能

spring-boot-engineer1.1萬turnstile-spin2146anysearch3729
SKILL.md
readonlyread-only
name
speech-to-text
description

使用 ElevenLabs Scribe v2 將音訊轉錄為文字。適用於將音訊/影片轉換為文字、產生字幕、轉錄會議或處理語音內容。

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 低延遲（約 150 毫秒） 即時轉錄、語音代理

含時間戳記的轉錄

逐字時間戳記包含類型分類和說話者識別：

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 可以將辨識出的說話者標記為 agent 和 customer，方法是同時設定 detect_speaker_roles=true 和 diarize=true。此選項與 use_multi_channel=true 不相容。

如果您的工作區有註冊的說話者設定檔，請在 diarize=true 的同時設定 use_speaker_library=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" \
  -F "use_speaker_library=true"

多聲道音訊

當每位說話者分別位於不同的音訊聲道時，請使用 use_multi_channel=true。預設情況下，API 會在 transcripts 下回傳每個聲道一個轉錄稿；設定 multichannel_output_style="combined" 可接收一個按時間戳記合併的轉錄稿，每個字會帶有 channel_index。

result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v2",
    use_multi_channel=True,
    multichannel_output_style="combined",
)

關鍵詞提示

協助模型辨識可能誤聽的特定詞彙 - 產品名稱、技術術語或特殊拼寫（最多 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

限制： 檔案大小最多 5.0GB，時長最多 10 小時

回應格式

{
  "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"轉錄失敗：{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')}")

即時串流

對於超低延遲（約 150 毫秒）的即時轉錄，請使用即時 API。即時 API 會產生兩種類型的轉錄稿：

  • 部分轉錄稿：隨著音訊處理而頻繁更新的中間結果 - 用於即時回饋（例如在使用者說話時顯示文字）
  • 已提交轉錄稿：在您「提交」後的最終穩定結果 - 用作應用程式的真實資料來源

「提交」告訴模型將當前區段定稿。您可以手動提交（例如在使用者暫停時），或使用語音活動偵測（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,
    includeLanguageDetection: true,
    onPartialTranscript: (data) => console.log("Partial:", data.text),
    onCommittedTranscript: (data) => setTranscript((prev) => prev + data.text),
  });

  const start = async () => {
    // 從後端取得 token（切勿將 API 金鑰暴露給客戶端）
    const { token } = await fetch("/scribe-token").then((r) => r.json());

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

  return <button onClick={start}>開始錄音</button>;
}

提交策略

策略 說明
手動 準備好時呼叫 commit() - 適用於檔案處理或當您控制音訊區段時
VAD 語音活動偵測在偵測到靜音時自動提交 - 適用於即時麥克風輸入

設定 includeLanguageDetection: true 可在包含時間戳記的已提交轉錄稿事件中接收偵測到的語言代碼。

// React：在 hook 上設定 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 發生錯誤

請參閱即時參考文件以取得完整說明。

參考資料