API de transcrição do Google Drive

Conecte uma mídia compartilhada no Google Drive a um fluxo de transcrição sem precisar mover primeiro o arquivo para seu aplicativo. Envie o link de compartilhamento acessível de um arquivo de áudio ou vídeo e consulte a tarefa até receber a transcrição.

Transcreva uma mídia compartilhada no Drive pelo backend

Um link público de compartilhamento do Drive pode servir como fonte de uma tarefa de transcrição assíncrona. Essa opção é útil quando colaboradores já entregam gravações pelo Drive e seu aplicativo precisa apenas da transcrição, das marcações de tempo e do status da tarefa.

Escolha a URL correta para um arquivo de áudio ou vídeo do Google Drive

Compartilhamentos de arquivo padrão: links drive.google.com/file/d/{file-id}/view são a opção mais clara para um arquivo de áudio ou vídeo enviado.
Compartilhamentos por identificador: links drive.google.com/open?id={file-id} e links de download do Drive podem ser resolvidos quando o mesmo arquivo está disponível para download público.
Somente arquivos de mídia reais: o arquivo de destino precisa conter áudio ou vídeo; uma pasta do Drive ou um documento do Google Workspace não é uma fonte de mídia.

Início rápido: coloque a transcrição de um arquivo de áudio ou vídeo do Google Drive na fila

Crie uma chave de API do Fast Transcriber e armazene-a em uma variável de ambiente no servidor. Envie a URL pública da mídia em source_url. Nunca exponha a chave Bearer no código do navegador nem a envie para o repositório do código-fonte.

curl --request POST https://fast-transcriber.com/api/v1/transcriptions \
  --header "Authorization: Bearer $FAST_TRANSCRIBER_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "source_url": "https://drive.google.com/file/d/FILE_ID/view?usp=sharing",
    "speaker_diarization": false
  }'

Uma solicitação válida retorna 202 Accepted. Isso significa que a tarefa entrou na fila, não que a fonte foi recuperada com sucesso. Leia o cabeçalho de resposta Location, atribua esse caminho a LOCATION_PATH e consulte-o até que o status da tarefa seja completed ou failed.

LOCATION_PATH="/api/v1/transcriptions/95c3fdd8-..."
curl --request GET "https://fast-transcriber.com$LOCATION_PATH" \
  --header "Authorization: Bearer $FAST_TRANSCRIBER_API_TOKEN"

Pronto para enviar esta solicitação? Crie uma chave de API ou consulte todos os endpoints na documentação da API.

Trabalhe com texto e segmentos com marcação de tempo

As tarefas concluídas contêm o texto da transcrição e os segmentos com marcação de tempo disponíveis conforme os limites do plano da conta autenticada. O mesmo formato de resposta permite que um aplicativo indexe um vídeo, acesse trechos citados, crie resumos ou encaminhe a transcrição para uma pesquisa autorizada ou um fluxo RAG.

{
  "data": {
    "id": "95c3fdd8-...",
    "filename": "video-source.mp4",
    "status": "completed",
    "duration_seconds": 84,
    "text": "Texto completo da transcrição...",
    "segments": [
      { "start": 0, "end": 3.8, "text": "Primeiro segmento..." }
    ]
  }
}

Defina speaker_diarization como true quando precisar identificar os locutores. A diarização exige uma conta Pro e usa os mesmos limites do aplicativo web.

O que os desenvolvedores criam com transcrições de um arquivo de áudio ou vídeo do Google Drive

Coleta de entrevistas: transforme gravações compartilhadas de pesquisa ou jornalismo em transcrições pesquisáveis depois que os colaboradores as enviarem.
Arquivos de reuniões: processe gravações exportadas e armazenadas em um local compartilhado e autorizado do Drive.
Entregas de produção: crie texto e marcações de tempo a partir de materiais de áudio ou vídeo entregues pelo Drive.

Links compatíveis e requisitos de acesso

A fonte precisa ser um arquivo real de áudio ou vídeo no Google Drive, com o Acesso geral definido como Qualquer pessoa com o link.

O arquivo precisa abrir e permitir download sem autenticação do Google.
Google Docs, Sheets, Slides, pastas e páginas comuns da web não são fontes de transcrição de áudio ou vídeo.
Se sua organização bloquear o compartilhamento público, recupere a mídia autorizada pela sua própria integração e use a API de envio direto.

Se uma gravação for privada e você tiver autorização para processá-la, recupere a mídia pelo seu próprio fluxo autenticado e use a API de envio direto de arquivos de áudio e vídeo.

Resolva problemas ao importar um arquivo de áudio ou vídeo do Google Drive

Verifique o Acesso geral: defina o arquivo como Qualquer pessoa com o link e confirme que ele abre em uma janela anônima sem solicitar a escolha de uma conta do Google.
Confira a resposta do download: o link precisa retornar a mídia, não uma página HTML de autorização, cota ou aviso de acesso.
Mantenha a autenticação do Drive privada no seu aplicativo: para arquivos restritos de uma organização, use sua própria integração autorizada com o Drive para recuperar os bytes e envie-os pela API de upload.

Planeje o tratamento de erros assíncronos

Uma integração em produção deve tratar fontes inválidas ou inacessíveis, falhas de autenticação, limites da conta e falhas temporárias de processamento. Erros HTTP imediatos usam o envelope {"error":{"code":"...","message":"..."}}. Ao consultar a tarefa, uma fonte que entrou na fila pode retornar data.status como failed, com detalhes em data.error. Não tente novamente indefinidamente com mídias privadas, removidas ou protegidas por login; mostre uma mensagem clara ou ofereça o envio autorizado do arquivo.

Perguntas frequentes

Qual configuração de compartilhamento do Drive é necessária?

O arquivo de mídia deve usar a opção Qualquer pessoa com o link e abrir sem autenticação do Google.

A API pode transcrever arquivos do Google Docs, Sheets ou Slides?

Não. Esse fluxo é exclusivo para arquivos de áudio e vídeo armazenados no Drive.

O que devo fazer com uma gravação privada no Drive?

Se tiver autorização para usá-la, recupere a mídia pelo seu fluxo autenticado do Drive e envie o arquivo pela API de envio direto.