异步文本转语音 | ElevenLabs Documentation

操作指南 · 假设你已完成文本转语音快速入门。

概述

Webhook 可在文本转语音转录任务完成时自动发送通知，无需持续轮询 API 获取状态更新。这对于耗时较长的转录任务或处理大量音频文件尤其有用。

转录完成后，ElevenLabs 会向指定的 webhook URL 发送 POST 请求，其中包含转录结果，包括转录文本、语言检测结果和所有元数据。

使用 webhook

本指南假设你已设置 API 密钥和 SDK。如果尚未完成，请先完成快速入门。

创建或编辑 webhook

在 ElevenLabs 控制台中，前往 开发者 > Webhooks。点击 创建 webhook，或编辑现有 webhook。

已选择 Transcription completed 的创建 webhook 对话框 — 创建或编辑 webhook 时选择 Transcription completed

按以下内容配置 webhook：

名称：便于识别的 webhook 名称
回调 URL：可公开访问的 HTTPS 端点
Webhook 身份验证方式：HMAC 或 OAuth。客户端需自行实现验证机制。ElevenLabs 会发送可用于验证的标头，但不会强制验证。
事件：选择 Transcription completed。

发起启用 webhook 参数的 API 调用

发起语音转文本 API 调用时，将 webhook 参数设为 true，即可为该请求启用 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_v3",
      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_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");
});

安全注意事项

签名验证

务必验证 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);

失败响应

返回 2xx 状态码以确认收到 webhook。

默认情况下，文本转语音转录 webhook 只会发送一次。每个非 2xx 响应都会被视为投递失败，多次失败会自动禁用 webhook。

如果为 webhook 启用重试，失败的投递（5xx、408、429 或连接错误）最多会额外重试 5 次，分别在上次尝试后约 30 秒、2 分钟、8 分钟、30 分钟和 30 分钟进行。其他 4xx 响应不会重试。同一事件的每次尝试都会携带相同的 ElevenLabs-Webhook-Delivery-Id 标头，因此处理程序可以忽略重复请求。

将 enable_logging 设为 false（零保留模式）的请求，在启用重试时最多会快速重试 2 次，分别在上次尝试后 5 秒和 30 秒进行。转录文本绝不会被存储。

如果投递仍然失败，请使用请求被接受时返回的 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_v3",
    webhook: true,
  });
  console.log("Test transcription started:", result.requestId);
}

后续步骤

服务端流式传输

使用基于 WebSocket 的流式 API 实时转录音频。

API 参考文档

完整的文本转语音 API 参考文档和参数。