Listar Gravações e Transcrições

Os endpoints GET /api/calls/{id}/recordings e GET /api/calls/{id}/transcriptions permitem listar os arquivos de gravação de uma chamada e, quando disponíveis, suas transcrições.

Como as gravações são organizadas

Cada chamada com gravação habilitada possui uma única gravação, que contém múltiplos arquivos:

fileType	Descrição	Formato
video	Gravação individual — um arquivo por participante	WebM (VP8/VP9 + Opus)
composite	Gravação composta — uma grade única com todos os participantes	MP4
transcription	Entrada somente de transcrição (sem vídeo) — aparece apenas no endpoint de transcrições, quando o projeto transcreve sem manter as gravações individuais	— (url e signed_url nulos)

Quais tipos aparecem na listagem depende da configuração do projeto: gravação individual e/ou gravação composta podem ser habilitadas ou desabilitadas de forma independente. O endpoint de gravações nunca retorna entradas transcription; o de transcrições retorna qualquer arquivo que possua transcrição, incluindo essas entradas sem vídeo.

Processamento assíncrono

Os arquivos são processados pelo nosso pipeline de processamento após o término da chamada (quando os participantes saem). Gravações individuais normalmente ficam disponíveis em poucos minutos; a gravação composta pode demorar mais, pois reprocessa a chamada inteira. A transcrição (se habilitada no projeto) chega depois da gravação, também de forma assíncrona.

Hoje não existe um webhook de "gravação pronta". Recomendamos consultar os endpoints de listagem periodicamente (polling) após receber o evento de fim da chamada via webhook.

Listar apenas transcrições de uma chamada

O endpoint GET /api/calls/{id}/transcriptions retorna somente os arquivos que já possuem transcrição disponível. A resposta tem exatamente o mesmo formato da listagem de gravações.

Requisição

GET https://api.videochamada.com.br/api/calls/{id}/transcriptions

Cabeçalhos:

Authorization: Bearer {API_TOKEN}

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
id	string (path)	Sim	ID da chamada
page	number (query)	Não	Página da listagem. Padrão: 1
limit	number (query)	Não	Itens por página (máximo 100). Padrão: 10

Exemplos

curl -X GET "https://api.videochamada.com.br/api/calls/{id}/transcriptions?page=1&limit=20" \
  -H "Authorization: Bearer {API_TOKEN}"

import requests

response = requests.get(
    "https://api.videochamada.com.br/api/calls/{id}/transcriptions",
    headers={"Authorization": "Bearer {API_TOKEN}"},
    params={"page": 1, "limit": 20},
)
print(response.json())

const response = await fetch(
  'https://api.videochamada.com.br/api/calls/{id}/transcriptions?page=1&limit=20',
  { headers: { Authorization: 'Bearer {API_TOKEN}' } },
);
const transcriptions = await response.json();

Resposta

Mesmo formato da listagem de gravações ({data: [...], pagination: {...}}), incluindo apenas os arquivos com transcription ou transcriptionData preenchidos.

Erros

Status	Mensagem	Quando
404	Call not found	A chamada não existe
403	Recording does not belong to this project	A chamada pertence a outro projeto (API key incorreta)
404	Call does not have recording enabled	A chamada não está com gravação habilitada

Diferenças entre os endpoints

Endpoint	Retorna
/api/calls/{id}/recordings	Todos os arquivos de gravação da chamada
/api/calls/{id}/transcriptions	Apenas arquivos com transcrição disponível

Diálogo consolidado

Se você precisa da conversa inteira em ordem cronológica, com os participantes intercalados, use o endpoint de diálogo da transcrição — ele consolida as transcrições de todos os participantes em uma única linha do tempo.

Boas práticas

• Polling após o fim da chamada: os arquivos aparecem na listagem alguns minutos após o término. Consulte periodicamente (por exemplo, a cada 1–2 minutos) até que os arquivos esperados estejam presentes.
• Use signed_url para download: o campo url é interno e não é acessível diretamente. Para baixar, use a signed_url da listagem ou o endpoint de download.
• Paginação: para chamadas com muitos participantes, percorra as páginas usando totalPages.
• Transcrições chegam depois: um arquivo pode aparecer na listagem de gravações antes de ter transcrição. Use o endpoint de transcrições quando precisar apenas dos arquivos já transcritos.