Integração da API Speech to Text: Guia para desenvolvedores

Uma API Speech to Text permite que desenvolvedores integrem reconhecimento e transcrição de voz diretamente em seus aplicativos. Mas antes de conectar a API STT, você precisa tomar algumas decisões de arquitetura.

Qual modo de transcrição você vai usar? Como vai lidar com arquivos de áudio longos? E como garantir que nomes de produtos ou nomes próprios sejam escritos corretamente? Um pouco de planejamento faz toda a diferença para criar uma solução escalável de API de Speech to Text nos seus aplicativos.

Este guia traz tudo o que você precisa para integrar a Speech to Text da ElevenLabs, com exemplos de código prontos para usar em produção. Tenha como referência o guia rápido de Speech to Text da ElevenLabs e o guia da API abertos em outra janela.

Resumo

• Existem dois modos de Speech to Text na ElevenLabs: batch (para áudios gravados) e realtime (para áudio ao vivo via WebSocket).
• O Scribe v2 faz transcrição batch em mais de 90 idiomas, com diarização de falantes, keyterm prompting, detecção de entidades, timestamps por palavra e suporte a múltiplos canais.
• Scribe v2 em Tempo Real faz transcrição ao vivo com latência de ~150ms, entregando transcrições parciais enquanto você fala e transcrições finais ao fim de cada segmento.
• Para arquivos com mais de 8 minutos, o Scribe v2 divide e transcreve em paralelo automaticamente. Para tarefas longas, use webhooks em vez de esperar pela resposta síncrona.
• O keyterm prompting direciona o modelo para termos específicos usando contexto – mais confiável do que listas de palavras-chave para nomes de produtos, termos técnicos ou nomes próprios incomuns.

Integração da API Speech to Text: Batch vs. realtime

Toda integração da API STT da ElevenLabs começa com uma escolha de arquitetura: batch ou realtime. Ambos oferecem um modelo STT avançado para seu ambiente de desenvolvimento, mas essa escolha impacta desde os recursos disponíveis até a latência de ponta a ponta.

Veja como os dois modos se comparam:

• Processamento em lote (Scribe v2): Recebe um arquivo de áudio ou vídeo completo, transcreve e retorna a transcrição em uma única resposta. Suporta o maior conjunto de recursos: até 1.000 keyterms, até 32 falantes para diarização, detecção de entidades, modo multicanal e webhooks para entrega assíncrona. Arquivos de até 3 GB e 10 horas são aceitos no modo padrão.
• Tempo real (Scribe v2 em Tempo Real): Aceita um fluxo de áudio ao vivo via WebSocket e retorna transcrições parciais e finais conforme o áudio chega, com latência de cerca de 150ms. Suporta até 50 keyterms e timestamps por palavra, sendo ideal para assistentes de voz, legendas ao vivo ou qualquer app onde o usuário fala e espera uma resposta imediata.

Vamos detalhar ainda mais as diferenças.

Regra rápida: use batch quando o áudio já está completo antes da transcrição e realtime quando você precisa transcrever o áudio enquanto ele é produzido.

Quando escolher Scribe v2 ou Scribe v2 Realtime

Batch e realtime atendem necessidades diferentes, então escolher o modo errado pode gerar retrabalho depois.

Veja como combinar o modelo com seu caso de uso:

• Scribe v2 é ideal quando o áudio está completo antes do processamento, como gravações de reuniões, transcrição de podcasts, arquivos de mídia ou qualquer coisa processada offline. Suporta todos os recursos, incluindo diarização, detecção de entidades e até 1.000 keyterms.
• Scribe v2 Realtime foi feito para áudio ao vivo. Aceita um stream via WebSocket e retorna transcrições conforme o áudio chega, sendo ideal para assistentes de voz ou qualquer cenário em que o usuário fala e seu app precisa responder antes do fim da fala.

Outro ponto importante é que a precisão varia conforme o idioma. Vale a pena conferir a taxa de erro de palavras antes de definir o mix de idiomas. O Scribe v2 publica as faixas de Word Error Rate (WER) para todos os mais de 90 idiomas suportados.

Precisão excelente (≤5% WER) cobre os principais idiomas europeus, japonês, indonésio, vietnamita, entre outros. Alta precisão (5-10% WER) cobre hindi, bengali, mandarim, coreano, georgiano, entre outros. Veja a divisão completa na documentação de suporte a idiomas para mais detalhes.

Como configurar a API Speech to Text da ElevenLabs

Para ter um cliente funcionando, basta seguir dois passos simples. Primeiro, instale o SDK. Depois, armazene suas credenciais com segurança.

Veja como fazer isso antes de enviar sua primeira solicitação de transcrição.

Instale o SDK e armazene sua chave de API como segredo usando um arquivo .env ou o gerenciador de segredos da sua plataforma. Nunca coloque sua chave de API diretamente no código.

Python

pip install elevenlabs
pip install python-dotenv

TypeScript

npm install @elevenlabs/elevenlabs-js

Crie um arquivo .env:

ELEVENLABS_API_KEY=<your_api_key_here>

Inicialize o cliente:

Python

import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

TypeScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

Sua primeira transcrição batch com a API STT da ElevenLabs

Agora que você inicializou o cliente, já pode enviar seu primeiro arquivo.

A API batch recebe um arquivo, transcreve e retorna o resultado completo de forma síncrona. O exemplo abaixo transcreve um arquivo de áudio remoto com diarização de falantes e marcação de eventos de áudio ativadas.

Python

# example.py
import os
from dotenv import load_dotenv
from io import BytesIO
import requests
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)

transcription = elevenlabs.speech_to_text.convert(
    file=audio_data,
    model_id="scribe_v2",          # Model to use
    tag_audio_events=True,          # Tag audio events like laughter, applause, etc.
    language_code="eng",            # Language of the audio file. If set to None, the model will detect the language automatically.
    diarize=True,                   # Whether to annotate who is speaking
)

print(transcription)

Execute:

python example.py

O objeto de resposta inclui o texto completo da transcrição, entradas por palavra com timestamps e IDs de falante, além de eventos de áudio detectados.

Cada palavra tem um campo type com um destes três valores:

• palavra: Para palavras transcritas do áudio.
• espaçamento: Espaços entre palavras em idiomas que usam espaço. Esse tipo não se aplica a vários idiomas, como japonês, cantonês e birmanês.
• evento_de_áudio: Marca qualquer som que não seja fala, como risadas ou tosse.

Veja como é a estrutura da resposta:

{
  "language_code": "en",
  "language_probability": 1,
  "text": "With a soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditative guides, or adding an intimate feel to your narrative projects.",
  "words": [
    {
      "text": "With",
      "start": 0.119,
      "end": 0.259,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 0.239,
      "end": 0.299,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "a",
      "start": 0.279,
      "end": 0.359,
      "type": "word",
      "speaker_id": "speaker_0"
    }
  ]
}

O campo language_probability mostra o nível de confiança do modelo na detecção do idioma, numa escala de 0,00 a 1,00.

Integração da API STT em tempo real

STT em tempo real segue um padrão um pouco diferente. Em vez de uma solicitação e uma resposta, você abre uma conexão WebSocket e lê as transcrições conforme chegam.

A API realtime usa um WebSocket para receber o áudio ao vivo e retornar transcrições conforme o áudio chega. Ela entrega dois tipos de transcrição:

• Transcrições parciais: Resultados intermediários que vão sendo atualizados conforme o modelo processa o áudio. Podem mudar.
• Transcrições finais: Resultados finais de um segmento de fala. Não mudam mais. Podem incluir timestamps por palavra se você ativar a opção "incluir timestamps".

A implementação no lado do cliente usa um token de uso único, não sua chave de API diretamente. Esse é um credencial temporário que expira em 15 minutos, gerado no servidor para que sua chave de API nunca fique exposta no navegador.

Passo 1: Gere um token de uso único (lado do servidor)

// Node.js server
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

app.get("/scribe-token", yourAuthMiddleware, async (req, res) => {
  const token = await elevenlabs.tokens.singleUse.create("realtime_scribe");

  res.json(token);
});

Passo 2: Conecte e transcreva (lado do cliente, React)

import { useScribe } from "@elevenlabs/react";

function MyComponent() {
  const scribe = useScribe({
    modelId: "scribe_v2_realtime",
    onPartialTranscript: (data) => {
      console.log("Partial:", data.text);
    },
    onCommittedTranscript: (data) => {
      console.log("Committed:", data.text);
    },
    onCommittedTranscriptWithTimestamps: (data) => {
      console.log("Committed with timestamps:", data.text);
      console.log("Timestamps:", data.words);
    },
  });

  const handleStart = async () => {
    // Fetch a single use token from the server
    const token = await fetchTokenFromServer();

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

  return (
    <div>
      <button onClick={handleStart} disabled={scribe.isConnected}>
        Start Recording
      </button>
      <button onClick={scribe.disconnect} disabled={!scribe.isConnected}>
        Stop
      </button>

      {scribe.partialTranscript && <p>Live: {scribe.partialTranscript}</p>}

      <div>
        {scribe.committedTranscripts.map((t) => (
          <p key={t.id}>{t.text}</p>
        ))}
      </div>
    </div>
  );
}

O hook useScribe gerencia o ciclo de vida da conexão WebSocket, acesso ao microfone e estado da transcrição. partialTranscript guarda o texto em andamento; committedTranscripts é o array crescente de segmentos finalizados.

Para streaming no servidor (transcrevendo áudio de uma URL ou arquivo, não do microfone), veja o guia de streaming no servidor.

Concorrência e escalabilidade para arquivos longos

Arquivos longos exigem um modelo de escalabilidade diferente da maioria das APIs. Vale entender isso antes de construir sua solução.

A concorrência na transcrição batch funciona diferente da maioria das APIs. Em vez de limitar o número de solicitações simultâneas, o Scribe v2 paraleliza arquivos longos automaticamente.

Arquivos com mais de 8 minutos são divididos em segmentos e transcritos ao mesmo tempo. O número de segmentos concorrentes é calculado assim:

Concurrency = min(4, round_up(audio_duration_secs / 480))

Na prática:

• Um arquivo de 15 minutos usa concorrência de 2
• Um arquivo de 120 minutos usa concorrência de 4 (máximo)

Arquivos de até 10 horas e 3 GB são aceitos no modo padrão. Observação: o modo multicanal tem limite menor de duração – veja a seção sobre transcrição multicanal abaixo.

Sobre formatos aceitos, a API STT suporta os formatos de áudio e vídeo mais comuns:

• Áudio: AAC, AIFF, OGG, MP3, OPUS, WAV, FLAC, M4A, WebM.
• Vídeo: MP4, AVI, MKV, MOV, WMV, FLV, WebM, MPEG, 3GPP.

Você pode enviar um arquivo de vídeo diretamente e receber a transcrição do áudio sem precisar processar antes.

Prompt de termos-chave

Modelos genéricos costumam errar nomes de marcas e termos técnicos. O keyterm prompting resolve isso.

O keyterm prompting direciona o modelo para palavras ou frases específicas na transcrição. É ideal quando seu áudio tem nomes de produtos, termos técnicos ou nomes próprios com grafia incomum.

Um diferencial do keyterm prompting é que ele usa contexto, sendo mais confiável que uma simples lista de palavras-chave. Se você informar "ElevenLabs" como keyterm, o modelo vai transcrever corretamente quando ouvir o nome da empresa. Sem isso, pode acontecer do modelo transcrever errado frases como "Trabalho na eleven labs há um ano".

Sem keyterm prompting:

I work at eleven labs.

Com keyterms=["ElevenLabs"]:

I work at ElevenLabs.

Batch aceita até 1.000 keyterms (50 caracteres cada). Realtime aceita até 50 keyterms (20 caracteres cada).

Transcrição batch com keyterms

Python

import os
from dotenv import load_dotenv
from io import BytesIO
import requests
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-keyterm-prompting.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)

transcription = elevenlabs.speech_to_text.convert(
    file=audio_data,
    model_id="scribe_v2",
    # Keyterms to prompt the model with.
    # Up to 1,000 keyterms can be provided, with a maximum length of 50 characters each
    keyterms=["ElevenLabs"],
)

print(transcription)

Streaming em tempo real com keyterms

Envie os keyterms ao conectar no WebSocket realtime:

Python

connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeUrlOptions(
    model_id="scribe_v2_realtime",
    keyterms=["ElevenLabs"],
))

Ou envie como parâmetros na URL do WebSocket:

wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v2_realtime&keyterms=ElevenLabs&keyterms=AnotherTerm

O keyterm prompting tem custo adicional. Veja a página de preços da API para detalhes.

Recursos avançados

Além do fluxo básico de transcrição da API STT, há vários recursos que enriquecem o resultado final. Veja alguns recursos avançados que você pode usar na sua API Speech to Text:

• Diarização de falantes para identificar quem está falando
• Modo no-verbatim para limpar a transcrição
• Detecção de entidades para sinalizar dados sensíveis
• Transcrição multicanal para separar canais de áudio

Vamos detalhar cada um deles.

Diarização de falantes

Ative diarize=True na sua solicitação batch para marcar quem está falando. O Scribe v2 suporta até 32 falantes. Cada palavra na resposta inclui um campo speaker_id (ex: speaker_0, speaker_1) que você pode usar para separar os trechos por falante.

A diarização é útil para transcrição de reuniões, entrevistas ou qualquer gravação com vários falantes, onde é importante saber quem disse o quê.

Modo no-verbatim

Quando no_verbatim=True, o modelo remove muletas, repetições e hesitações da transcrição. "É... T-talvez a gente deva, ah, escolher a opção A" vira "Talvez a gente deva escolher a opção A."

Isso gera um resultado mais limpo para legendas, resumos ou qualquer uso em que a leitura seja mais importante do que registrar cada som falado. Está disponível tanto para batch (scribe_v2) quanto para realtime (scribe_v2_realtime).

Detecção e remoção de entidades

O Scribe v2 pode detectar e marcar entidades na transcrição, com timestamps exatos para cada entidade detectada. As categorias incluem PII (nomes, números de cartão, CPFs), PHI (condições médicas) e PCI (informações de pagamento), entre outras. Para a lista completa de tipos de entidades, veja a documentação de detecção de entidades.

Isso é especialmente útil para conformidade, permitindo identificar e remover automaticamente informações sensíveis antes de armazenar ou exibir a transcrição.

A detecção de entidades tem custo adicional de $0,070 (por hora) além do valor base da transcrição. Veja a página de preços da API para detalhes.

Transcrição multicanal

Quando use_multi_channel=True, cada canal de áudio é transcrito separadamente e recebe um ID de falante conforme o número do canal. Até 5 canais são suportados. O tempo máximo de arquivo no modo multicanal é 1 hora.

O modo multicanal é útil quando você tem uma faixa de áudio por falante – por exemplo, gravação de call center onde cada participante está em um canal. Isso gera atribuição de falante mais precisa do que a diarização em um arquivo mono.

Entrega assíncrona com webhooks

Fazer polling funciona para baixo volume, mas não escala quando você começa a trabalhar com arquivos longos ou pipelines de alto volume. Webhooks resolvem isso enviando o resultado para você.

Para arquivos longos ou pipelines de transcrição em grande volume, esperar pela resposta síncrona nem sempre é prático. Webhooks permitem enviar a solicitação e receber o resultado no seu endpoint quando o processamento terminar, sem precisar fazer polling.

Como configurar um webhook

No painel da ElevenLabs, acesse Desenvolvedores > Webhooks, clique em Criar webhook e configure:

• Nome: Dê um nome descritivo e fácil de lembrar para seu webhook.
• URL de callback: Adicione um endpoint HTTPS público ao webhook.
• Método de autenticação do webhook: Selecione HMAC ou OAuth (opcional, mas altamente recomendado para segurança).
• Eventos: Selecione Transcription completed nas opções.

Enviando uma transcrição com entrega via webhook

Python

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

Quando webhook=True, a solicitação retorna antes da transcrição. O resultado final é enviado para seu endpoint via POST quando o processamento termina.

Como implementar seu endpoint de 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' });
  }
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Estrutura do payload do webhook

Seu endpoint recebe um POST com o seguinte formato:

{
  "type": "speech_to_text_transcription",
  "data": {
    "request_id": "some-request-id-123",
    "webhook_metadata": {},
    "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"
        }
      ]
    }
  }
}

Boas práticas de segurança para webhooks

Ao trabalhar com webhooks, siga algumas medidas de segurança para garantir que os eventos sejam entregues e processados corretamente.

• Verifique as assinaturas do webhook: Sempre verifique as assinaturas usando elevenlabs.webhooks.constructEvent() para garantir que vêm da ElevenLabs.
• Use endpoints HTTPS: URLs de webhook devem usar HTTPS para proteger os dados em trânsito.
• Retorne o status HTTP adequado: Retorne 200-299 para sucesso, 400-499 para erros do cliente (não serão reenviados) e 500-599 para erros do servidor (serão reenviados).
• Use uma ferramenta de túnel para desenvolvimento local: No desenvolvimento local, use uma ferramenta como ngrok para expor seu servidor local com uma URL HTTPS pública.

Com essas estratégias, você pode usar webhooks com tranquilidade.

Principais pontos para sua integração com a API Speech to Text

Uma integração de produção com a API Speech to Text depende de algumas decisões-chave.

Acertando nessas escolhas, o resto flui naturalmente:

• Escolha o modo conforme o caso de uso: Use batch (scribe_v2) quando o áudio já está completo antes do processamento. Use realtime (scribe_v2_realtime) quando precisa transcrever enquanto o áudio é produzido, como para agentes, assistentes de voz ou legendas ao vivo.
• Use keyterms para precisão em vocabulário específico: Envie nomes de produtos, termos técnicos ou nomes próprios incomuns como keyterms. O modelo usa contexto para aplicar corretamente sem exagerar.
• Deixe a API cuidar de arquivos longos: Arquivos com mais de 8 minutos são paralelizados automaticamente, então você não precisa dividir manualmente. Arquivos de até 10 horas e 3 GB são aceitos no modo padrão.
• Use webhooks para pipelines assíncronos: Para tarefas longas ou processamento em alto volume, webhook=True permite enviar e seguir com o fluxo. Sempre verifique a assinatura de cada payload recebido.
• Ative o modo no-verbatim para saída limpa: Se seu uso for legendas, resumos ou processamento NLP, no_verbatim=True remove automaticamente muletas e hesitações.
• Use o modo multicanal para faixas de áudio separadas: Se sua gravação tem um canal por falante (call center, entrevistas), a transcrição multicanal gera atribuição de falante mais precisa do que a diarização em arquivo misto. Lembre-se do limite de 1 hora nesse modo.

Se quiser mais informações, confira a referência completa da API como ponto de partida.

Crie sua integração Speech to Text com o ElevenAPI

Depois de ler este guia, você tem todos os padrões necessários para uma integração de produção com a API Speech to Text. Seja para transcrição batch ou realtime, incluindo recursos avançados como keyterm prompting e entrega assíncrona, você está pronto para lançar seu app com STT integrado.

Comece aprendendo mais sobre a API Speech to Text ou cadastre-se para fazer sua primeira chamada com o ElevenAPI hoje mesmo.

Perguntas frequentes sobre integração da API STT