异步 Speech to Text | ElevenLabs Documentation

操作指南 · 假设你已完成 Speech to Text 快速入门。

概述

Webhook 可在 Speech to Text 转录任务完成时自动发送通知，无需持续轮询 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 调用

发起语音转文本 API 调用时，添加值为 true 的 webhook 参数，为该请求启用 webhook 通知。

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"
        }
      ]
    }
  }
}

请参阅语音转文本 API 参考文档，了解响应结构的详细信息。

如果请求包含 transcript_edit 指令，transcription 对象还会包含一个带有编辑后文本的 edited_transcript 字段。

实现 webhook 端点

以下示例展示如何实现 webhook 端点来处理传入通知：

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

安全注意事项

签名验证

始终验证 webhook 签名，确保请求来自 ElevenLabs。

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

失败响应

返回适当的 HTTP 状态码：

200-299：成功 - webhook 已成功处理
400-499：客户端错误 - 不会重试 webhook
500-599：服务器错误 - 将重试 webhook

测试 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 参考文档

完整的 Speech to Text API 参考文档和参数说明。