Seis Provedores de Transcrição, Uma API

Escolher um provedor de speech-to-text não é uma decisão que se toma apenas uma vez. A precisão no seu domínio, o preço por hora, os idiomas necessários, se o fornecedor assinará um DPA com os dados permanecendo na UE e como a separação de interlocutores se comporta quando três pessoas falam ao mesmo tempo — tudo isso muda, e a resposta não é a mesma para cada cliente.

Por isso, paramos de escolher. Você seleciona o provedor por bot e pode mudar de ideia em uma gravação que já existe.

O que você pode escolher

O ElevenLabs é somente streaming. Os outros cinco suportam ambos.

Batch é o que a maioria das pessoas quer: a reunião termina, o áudio é enviado, um webhook retorna a transcrição com identificação de interlocutores e timings no nível da palavra. Live significa segmentos de transcrição chegando via WebSocket enquanto a reunião ainda está em andamento, para situações que precisam reagir em tempo real.

Eles são configurados de forma independente, e você pode executar ambos no mesmo bot com provedores diferentes se quiser um feed live rápido e uma transcrição final mais precisa.

Batch

{
  "meeting_url": "https://meet.google.com/abc-defg-hij",
  "bot_name": "Recording Bot",
  "transcription_enabled": true,
  "transcription_config": {
    "provider": "speechmatics",
    "region": "eu2",
    "api_key": null,
    "custom_params": null
  }
}

Quatro campos. provider tem como padrão "gladia" se omitido. region, api_key e custom_params têm padrão null e são abordados abaixo.

transcription_config é obrigatório quando transcription_enabled é true e ignorado quando é false.

Assim que o bot finaliza, transcription_provider e transcription_ids retornam no registro do bot e no payload do webhook, e GET /v2/bots/:bot_id/status reporta o transcription_status live consultado diretamente do provedor: not-applicable, not-started, queued, processing, done ou error.

Fixação de região

A maioria desses provedores opera em mais de uma região, e para muitos dos nossos clientes isso é o ponto central.

Envie uma região que o provedor não possui e você receberá um erro 400 na criação do bot com os valores permitidos listados, em vez de uma surpresa mais tarde. A API batch da Gladia é somente global, e passar region com provider: "gladia" na configuração batch é rejeitado por esse motivo. Sua API live possui regiões.

Deixe region como null e selecionamos um padrão adequado: eu para Deepgram e AssemblyAI, eu1 para Speechmatics, us para Soniox.

Se você precisar que o áudio nunca saia de uma jurisdição, combine isso com armazenamento próprio. Os provedores buscam o áudio a partir de uma URL assinada no bucket, portanto a localização do bucket e a região do provedor juntos determinam onde o áudio realmente vai.

Use sua própria key

Passe api_key e usaremos sua conta naquele provedor em vez da nossa.

{
  "transcription_config": {
    "provider": "deepgram",
    "region": "eu",
    "api_key": "your-deepgram-key"
  }
}

As keys são criptografadas com AES-256-GCM antes de serem armazenadas e permanecem criptografadas em trânsito até o bot, que descriptografa no ponto de uso. Quando você exclui os dados de um bot, a key armazenada é sobrescrita.

Dois motivos para usar isso. O primeiro é custo: a transcrição com nossa key cobra 0,25 tokens por hora; com a sua, 0,05. O segundo é que algumas funcionalidades só são possíveis na sua própria conta, como um vocabulário personalizado que você treinou ou um contrato com termos que não possuímos.

BYOK está disponível em todos os planos, incluindo Pay as You Go. Passe sua API key do provedor em transcription_config; nenhum upgrade de plano é necessário.

Opções do provedor, repassadas diretamente

Deliberadamente não construímos uma camada de opções normalizada. Cada provedor tem funcionalidades que os outros não têm, e nivelá-las a um denominador comum significaria descartar o motivo pelo qual você escolheu aquele provedor.

custom_params é enviado ao provedor mais ou menos como você escreveu:

{
  "transcription_config": {
    "provider": "speechmatics",
    "region": "eu2",
    "custom_params": {
      "transcription_config": {
        "language": "en",
        "diarization": "speaker",
        "operating_point": "enhanced"
      }
    }
  }
}

A notação de ponto também funciona, se for mais fácil de construir:

{ "custom_params": { "diarization_config.min_speakers": 2 } }

Na configuração live, o valor é desaninhado antes da validação, portanto você valida a estrutura que o provedor realmente receberá. Na configuração batch, a chave plana é validada como escrita e desaninhada posteriormente, no momento do envio.

Na configuração live, quatro campos são definidos pelo pipeline e rejeitados se você os enviar: encoding, sample_rate, bit_depth, channels. A taxa de amostragem em particular é negociada por provedor a partir do áudio da reunião, portanto sobrescrevê-la quebraria o stream. Use streaming_config.audio_frequency em vez disso.

A separação de interlocutores é ativada por padrão, pois sem ela você obtém um bloco de texto sem identificação de interlocutores, e pelo menos um provedor silenciosamente não retorna nenhuma utterance a menos que seja solicitado. Um valor explícito em custom_params tem precedência.

O problema: batch e live aceitam estruturas diferentes

Esse é o ponto que custa uma tarde de trabalho às pessoas, então vale a pena dizer claramente. Para o mesmo provedor, a API live e a API batch não aceitam a mesma estrutura de parâmetros.

O Gladia é o exemplo mais claro. O batch aceita a configuração de tradução no nível superior. O live quer ela aninhada sob realtime_processing:

{
  "streaming_config": {
    "mode": "transcription",
    "output_url": "wss://your-app.example.com/transcripts",
    "audio_frequency": 24000,
    "transcription": {
      "provider": "gladia",
      "region": "eu-west",
      "api_key": "your-gladia-key",
      "custom_params": {
        "language_config": { "languages": ["ru"] },
        "realtime_processing": {
          "translation": true,
          "translation_config": { "target_languages": ["en"] }
        }
      }
    }
  }
}

Os parâmetros live são validados em modo estrito, pois as APIs de sessão live rejeitam chaves desconhecidas imediatamente e preferimos falhar na criação do bot a falhar na sua reunião. Quando você envia uma chave que pertence a um nível abaixo, o erro indica onde ela deve ir:

'translation' is not a top-level field of the gladia live API —
did you mean 'realtime_processing.translation'?
(the live API shape differs from batch)

Tanto os parâmetros batch quanto live são verificados contra o schema de cada provedor na criação do bot, portanto um erro de digitação retorna como um 400 em um segundo em vez de uma transcrição com falha uma hora depois. Duas ressalvas sobre o rigor dessa verificação. O parsing batch é permissivo, portanto uma chave batch desconhecida passa na validação e é encaminhada para o provedor tratar; somente o live rejeita chaves desconhecidas. E os parâmetros live do ElevenLabs são repassados sem validação, pois não há um schema publicado para verificarmos.

Saída live

Com mode: "transcription", abrimos a sessão do provedor, alimentamos o áudio da reunião e encaminhamos eventos para seu output_url como JSON:

{
  "event": "transcript.segment",
  "bot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "text": "so the migration lands Thursday",
    "isFinal": true,
    "utteranceStart": 12.44,
    "utteranceEnd": 14.91,
    "confidence": 0.97,
    "speaker": { "name": "Alice", "id": 1 },
    "words": []
  }
}

Também session.started com o provedor utilizado, translation quando você solicitou, e error. Enviamos um ping a cada 30 segundos para evitar que intermediários fechem um socket ocioso.

Uma restrição: as sessões live com nossa platform key estão limitadas a um conjunto gerenciado de provedores, atualmente o Gladia. Qualquer outro provedor para transcrição live requer uma BYOK key, e rejeitamos isso na criação do bot com FST_ERR_STREAMING_TRANSCRIPTION_KEY_UNAVAILABLE em vez de descobrir quando a reunião começa.

Mudando de ideia

POST /v2/bots/:bot_id/retranscribe

{
  "transcription": {
    "provider": "assemblyai",
    "region": "eu",
    "api_key": "your-assemblyai-key"
  }
}

O áudio armazenado é reenviado a um provedor diferente e a configuração do bot é atualizada. É assim que você faz testes A/B com dois fornecedores nas suas próprias reuniões em vez de no áudio de demonstração deles, e é assim que você recupera uma transcrição que falhou.

Excluir os dados de um bot remove a transcrição do provedor também, com ?delete_from_provider=true (o padrão), usando sua própria key onde você forneceu uma.

O que acontece quando um provedor tem um dia ruim

Um envio com falha é tentado novamente duas vezes, em 5 e 15 segundos, totalizando três tentativas. Apenas erros em que uma nova tentativa poderia possivelmente funcionar são elegíveis: rate limits, 5xx, timeouts de conexão e polling, falhas no nível de rede e o caso em que o provedor retornou um 2xx com um body sem nenhum job id. Erros de autenticação, entrada inválida e operações não suportadas nunca são tentados novamente, pois falhariam da mesma forma na segunda vez.

Cada nova tentativa rotaciona o callback secret antes de reenviar. Isso resolve uma condição de corrida real: se o provedor efetivamente aceitou um job cuja resposta expirou no nosso lado, seu callback chega com um secret que não existe mais e é rejeitado, em vez de concorrer com o job reenviado e produzir duas transcrições para um único chunk.

Não há failover automático para um segundo provedor, e prefiro dizer isso claramente a que você descubra durante um incidente. Se o provedor escolhido falhar após as novas tentativas, o bot termina em failed com TRANSCRIPTION_FAILED, e a gravação e os artefatos de áudio continuam disponíveis. A recuperação é uma chamada retranscribe, opcionalmente indicando um provedor diferente. Trocar de fornecedor silenciosamente significaria uma transcrição em uma jurisdição que você não concordou, a um preço que você não concordou — portanto, é uma decisão que deixamos com você.

Relacionados

• Armazenamento Próprio — controle onde o áudio que o provedor lê realmente fica armazenado
• Referência da API Meeting BaaS