Transcrição em lote

1. 1

   Envie o áudio

   Mande o arquivo em multipart/form-data, no campo file (até 500 MB), ou um JSON com url. Termos-chave (keyterms) reforçam nomes próprios, remédios e jargão: até 100, com até 50 caracteres cada. No formulário, repita o campo keyterms uma vez por termo.

   cURLPythonJavaScript

   Copiar

   curl https://api.int8labs.com/v1/stt/transcriptions \
     -H "Authorization: Bearer $INT8_API_KEY" \
     -F "file=@consulta.m4a" \
     -F "keyterms=Dra. Helena Prado" \
     -F "keyterms=losartana" \
     -F "webhook_url=https://api.suaempresa.com.br/int8"

   A resposta é 202 com o job na fila. Para mandar uma URL em vez do arquivo:

   cURLPythonJavaScript

   Copiar

   curl https://api.int8labs.com/v1/stt/transcriptions \
     -H "Authorization: Bearer $INT8_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"url": "https://arquivos.suaempresa.com.br/consulta.m4a", "keyterms": ["Dra. Helena Prado"], "webhook_url": "https://api.suaempresa.com.br/int8"}'

   A URL precisa ser http ou https e pública: endereço de rede interna, localhost e afins são recusados. O download tem até 60 s e 500 MB.

2. 2

   Acompanhe o job

   O job passa por queued, processing e completed (ou failed). Consulte com GET /v1/stt/transcriptions/{id} ou, melhor, receba o webhook do passo 3. Para áudio de até 10 minutos, wait=true devolve o resultado na própria resposta, com status 200.

   queuedna fila; até 2 jobs por organização processam ao mesmo tempo

   processingo worker pegou o job e está transcrevendo

   completedresult com text e segments; cobrado

   failederror com code e message; não cobra

   canceledcancelado com DELETE antes de terminar; não cobra

   cURLPythonJavaScript

   Copiar

   curl https://api.int8labs.com/v1/stt/transcriptions/0f8e2a6c-3b1d-4c9e-8a7f-5d2b1e9c4a60 \
     -H "Authorization: Bearer $INT8_API_KEY"

   O resultado traz o texto e os trechos, com início e fim em milissegundos:

   Resposta200

   {
     "id": "0f8e2a6c-3b1d-4c9e-8a7f-5d2b1e9c4a60",
     "status": "completed",
     "source": "api",
     "input": "upload",
     "file_name": "consulta.m4a",
     "size_bytes": 24117248,
     "duration_ms": 2538000,
     "keyterms": [
       "Dra. Helena Prado",
       "losartana"
     ],
     "webhook_url": "https://api.suaempresa.com.br/int8",
     "cost_brl": 0.07755011,
     "error": null,
     "result": {
       "text": "bom dia dona ana paula tudo bem com a senhora trouxe sim doutora o de sangue e o eletrocardiograma",
       "segments": [
         {
           "start_ms": 0,
           "end_ms": 14120,
           "text": "bom dia dona ana paula tudo bem com a senhora"
         },
         {
           "start_ms": 14120,
           "end_ms": 31480,
           "text": "trouxe sim doutora o de sangue e o eletrocardiograma"
         }
       ],
       "duration_ms": 2538000
     },
     "created_at": "2026-10-13T14:30:02.118Z",
     "started_at": "2026-10-13T14:30:02.540Z",
     "completed_at": "2026-10-13T14:31:10.902Z",
     "expires_at": "2026-11-12T14:31:10.902Z"
   }

3. 3

   Receba o webhook

   Com webhook_url, mandamos transcription.completed ou transcription.failed para a sua URL, assinado com o segredo da organização. São até 3 tentativas: a primeira sai na hora, a segunda 30 s depois da primeira falhar e a terceira 5 min depois da segunda falhar; se a API reiniciar no meio, as pendentes se perdem (consulte o job com GET). Veja Webhooks para verificar a assinatura.

4. 4

   Exporte legendas

   GET /v1/stt/transcriptions/{id}/export?format=srt devolve a legenda; também há txt (o texto) e vtt. Exportar um job que ainda não concluiu volta 409 conflict.

   cURLPythonJavaScript

   Copiar

   curl "https://api.int8labs.com/v1/stt/transcriptions/0f8e2a6c-3b1d-4c9e-8a7f-5d2b1e9c4a60/export?format=srt" \
     -H "Authorization: Bearer $INT8_API_KEY" \
     --output consulta.srt

   1
   00:00:00,000 --> 00:00:14,120
   bom dia dona ana paula tudo bem com a senhora
   
   2
   00:00:14,120 --> 00:00:31,480
   trouxe sim doutora o de sangue e o eletrocardiograma
   

Retenção

DELETE /v1/stt/transcriptions/{id} cancela um job na fila ou processando (nada é cobrado) e apaga na hora o resultado de um job que já terminou.

Cobrança e saldo

A cobrança é por segundo de áudio, quando o job conclui: uma hora sai R$ 0,11. Job que falha ou é cancelado não cobra. Na criação, o saldo precisa cobrir o custo estimado do job somado ao dos jobs da organização que ainda estão na fila; senão, a resposta é 402 insufficient_balance antes de processar.

Formatos e limites

• Formatos: wav, mp3, m4a/aac, ogg/opus, flac, webm e mp4 (o áudio do vídeo).
• Tamanho: até 500 MB por arquivo (no playground do console, 100 MB).
• Duração: até 4 horas.
• Simultaneidade: 2 jobs da organização processam ao mesmo tempo; os outros esperam na fila.
• Arquivo ilegível: 415 unsupported_media na criação, ou o job falha com unsupported_media se o áudio decodificado não bate com o cabeçalho.