Speech to Text assíncrono

Visão geral

Os webhooks permitem receber notificações automáticas quando suas tarefas de transcrição do Speech to Text são concluídas, eliminando a necessidade de consultar continuamente a API em busca de atualizações de status. Isso é especialmente útil para tarefas de transcrição de longa duração ou ao processar grandes volumes de arquivos de áudio.

Quando uma transcrição é concluída, a ElevenLabs envia uma solicitação POST para a URL de webhook especificada com os resultados da transcrição, incluindo o texto transcrito, a detecção de idioma e quaisquer metadados.

Como usar webhooks

1

Criar ou editar um webhook

No painel da ElevenLabs, acesse Desenvolvedores > Webhooks. Clique em Criar webhook ou edite um webhook existente.

Configure o webhook com:

• Nome: um nome descritivo para seu webhook
• URL de callback: seu endpoint HTTPS acessível publicamente
• Método de autenticação do webhook: HMAC ou OAuth. Cabe ao cliente implementar o mecanismo de verificação. A ElevenLabs envia cabeçalhos que permitem a verificação, mas não a exigimos.
• Eventos: selecione Transcrição concluída.

2

Fazer chamadas de API com o parâmetro de webhook ativado

Ao fazer chamadas à API de Speech to Text, inclua o parâmetro webhook definido como true para ativar notificações de webhook para essa solicitação específica.

PythonTypeScript

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

Payload do webhook

Quando uma transcrição é concluída, seu endpoint de webhook recebe uma solicitação POST com os dados da transcrição e do webhook:

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

Consulte a referência da API de Speech to Text para saber mais sobre os detalhes da estrutura da resposta.

Se a solicitação incluiu uma instrução transcript_edit, o objeto transcription também contém um campo edited_transcript com o texto editado.

Se a transcrição falhar, seu endpoint receberá um evento webhook_error. Ele não tem um objeto data: contém um request_id de nível superior (o mesmo ID retornado quando a solicitação foi aceita), um error_message e o webhook_metadata da solicitação.

Como implementar seu endpoint de webhook

Veja um exemplo de como implementar um endpoint de webhook para processar notificações recebidas:

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

Considerações de segurança

Verificação de assinatura

Sempre verifique as assinaturas do webhook para garantir que as solicitações vieram da ElevenLabs.

Requisito de HTTPS

As URLs de webhook devem usar HTTPS para garantir a transmissão segura dos dados de transcrição.

Limitação de taxa

Implemente limitação de taxa no seu endpoint de webhook para evitar abusos:

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

Respostas a falhas

Retorne um código de status 2xx para confirmar o recebimento do webhook.

Por padrão, os webhooks de transcrição do Speech to Text são enviados uma vez. Toda resposta diferente de 2xx conta como uma entrega com falha, e falhas repetidas desativam automaticamente o webhook.

Se você ativar as novas tentativas para o webhook, entregas com falha (5xx, 408, 429 ou erros de conexão) serão repetidas até mais 5 vezes, aproximadamente 30 segundos, 2 minutos, 8 minutos, 30 minutos e 30 minutos após a tentativa anterior. Outras respostas 4xx não são repetidas. Todas as tentativas para o mesmo evento incluem o mesmo cabeçalho ElevenLabs-Webhook-Delivery-Id, para que seu manipulador possa ignorar duplicatas.

Solicitações feitas com enable_logging definido como false (modo de retenção zero) recebem até 2 novas tentativas rápidas, 5 segundos e 30 segundos após a tentativa anterior, quando as novas tentativas estão ativadas. A transcrição nunca é armazenada.

Se uma entrega ainda falhar, busque o resultado com Obter transcrição usando o transcription_id retornado quando a solicitação foi aceita. As transcrições não são armazenadas para solicitações feitas com enable_logging definido como false.

Como testar webhooks

Desenvolvimento local

Para testes locais, use ferramentas como o ngrok para expor seu servidor local:

ngrok http 3000

Use a URL HTTPS fornecida como seu endpoint de webhook durante o desenvolvimento.

Teste de webhook

Você pode testar sua implementação de webhook fazendo uma solicitação de transcrição e monitorando seu endpoint:

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

Próximas etapas