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.

Transcrição sem gravação de vídeo

É possível transcrever sem disponibilizar gravações de vídeo. No painel, edite o projeto e configure:

• Transcrição: ligada (enableTranscription: true).
• Gravação, gravação individual e gravação composta: desligadas (enableRecording, enableIndividualRecording e enableCompositeRecording: false).

A transcrição precisa capturar e processar o áudio da conversa. Desligar as saídas de vídeo não desliga essa captura; desligar também a transcrição impede a geração de texto.

Na API, crie a chamada com POST /api/calls omitindo recording para herdar a configuração do projeto. Não há um campo transcription nesse endpoint. Revogar a captura durante a chamada com DELETE /api/calls/{id}/recordings interrompe também o áudio usado para novas transcrições.

Após o processamento, consulte GET /api/calls/{id}/transcriptions para obter os textos por participante ou o diálogo consolidado. Use uma chave do mesmo projeto com o escopo transcriptions.read.

Desligar a captura não apaga textos já produzidos nem impede sua consulta. Uma resposta data: [] significa que ainda não há texto disponível: aguarde o processamento e confirme se a transcrição estava ligada durante a chamada. Habilitá-la depois não recupera áudio que não foi capturado.

Como as gravações são organizadas

Cada chamada com captura para gravação ou transcrição 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	— (sem URL de vídeo)

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, quando habilitada no projeto, também é assíncrona e pode ficar pronta em outro momento; ela não depende de um vídeo disponível para download.

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 usa o mesmo envelope de paginação, mas contém os textos e metadados das sessões, sem URLs de download de mídia.

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

Envelope {data: [...], pagination: {...}}, incluindo apenas arquivos com transcription ou transcriptionData preenchidos. Cada item contém os textos, a sessão, o nome do participante quando disponível e metadados de duração; não inclui url, signed_url nem expires_at.

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)
401	Erro de autenticação	Chave ausente ou inválida
403	Erro de permissão	Chave sem o escopo transcriptions.read

Diferenças entre os endpoints

Endpoint	Retorna
/api/calls/{id}/recordings	Arquivos de vídeo habilitados para o projeto; exige recordings.read
/api/calls/{id}/transcriptions	Textos disponíveis, inclusive sem vídeo; exige transcriptions.read

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.
• Download de vídeo é separado: use a listagem de gravações ou o endpoint de download com a permissão correspondente. A consulta de transcrições não fornece URLs de mídia.
• Paginação: para chamadas com muitos participantes, percorra as páginas usando totalPages.
• Consulte o texto diretamente: não espere aparecer um vídeo para consultar transcrições. No modo somente transcrição, a listagem de gravações fica vazia.