Speech to Text assíncrono | ElevenLabs Documentation

Guia prático · Pressupõe que você concluiu o início rápido do Speech to Text .

Visão geral

Os webhooks permitem que você receba notificações automáticas quando suas tarefas de transcrição de 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 trabalhos 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 o URL de webhook especificado com os resultados da transcrição, incluindo o texto transcrito, a detecção de idioma e quaisquer metadados.

Como usar webhooks

Este guia pressupõe que você configurou sua chave de API e o SDK. Conclua primeiro o início rápido, caso ainda não tenha feito isso.

Criar ou editar um webhook

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

Caixa de diálogo Criar webhook com Transcrição concluída selecionada — Selecione Transcrição concluída ao criar ou editar o webhook

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 impomos.
Eventos: selecione Transcrição concluída.

Fazer chamadas à 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 por webhook nessa solicitação específica.

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 de 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.

Como implementar seu endpoint de webhook

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

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

Considerações de segurança

Verificação de assinatura

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

Exigência de HTTPS

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

Limitação de taxa

Implemente a 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 em caso de falha

Retorne os códigos de status HTTP apropriados:

200-299: sucesso — webhook processado com êxito
400-499: erro do cliente — não haverá nova tentativa de webhook
500-599: erro do servidor — haverá nova tentativa de webhook

Como testar webhooks

Desenvolvimento local

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

ngrok http 3000

Use o URL HTTPS fornecido 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

Streaming no servidor

Transcreva áudio em tempo real usando a API de streaming baseada em WebSocket.

Referência da API

Referência completa e parâmetros da API de Speech to Text.