Início rápido

Este guia percorre o fluxo completo da API: criar um upload, enviar o arquivo de midia, concluir o upload, criar uma tarefa de transcricao e consultar os resultados.

Acesse Video To Text para gerenciar sua conta, criar chaves de API e voltar ao workspace do produto.

Defina a URL base da API e a chave:

export VTT_API_BASE_URL="https://api.videototext.dev"
export VTT_API_KEY="vtt_xxxxx"

1. Criar um upload

Crie uma URL de upload assinada para o arquivo de midia.

curl -X POST "https://api.videototext.dev/v1/uploads" \
  -H "Authorization: Bearer $VTT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "meeting.mp4",
    "mimetype": "video/mp4"
  }'

A resposta inclui os campos necessarios para as proximas etapas:

{
  "data": {
    "uploadUrl": "https://storage.example.com/signed-upload-url",
    "fileKey": "uploads/example.mp4",
    "fileUrl": "https://static.example.com/uploads/example.mp4",
    "uploadId": "00000000-0000-0000-0000-000000000000",
    "expiresAt": "2026-06-06T10:00:00.000Z"
  },
  "meta": {}
}

2. Enviar o arquivo

Envie o arquivo binario diretamente para uploadUrl. Use o mesmo valor de Content-Type informado ao criar o upload.

curl -X PUT "https://storage.example.com/signed-upload-url" \
  -H "Content-Type: video/mp4" \
  --data-binary "@meeting.mp4"

3. Concluir o upload

Conclua a sessao de upload para que a Video To Text possa validar o objeto e criar um asset.

curl -X POST "https://api.videototext.dev/v1/uploads/$UPLOAD_ID/operations/complete" \
  -H "Authorization: Bearer $VTT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileKey": "uploads/example.mp4",
    "fileUrl": "https://static.example.com/uploads/example.mp4",
    "filename": "meeting.mp4",
    "mimetype": "video/mp4",
    "fileSize": 10485760
  }'

A resposta retorna o assetId usado para criar uma tarefa de transcricao.

{
  "data": {
    "assetId": "00000000-0000-0000-0000-000000000000"
  },
  "meta": {}
}

4. Criar uma tarefa de transcricao

Crie a tarefa a partir do asset enviado. O modo padrao e balanced.

curl -X POST "https://api.videototext.dev/v1/tasks" \
  -H "Authorization: Bearer $VTT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assetId": "00000000-0000-0000-0000-000000000000",
    "language": "Auto",
    "timestampMode": "CHUNK",
    "transcriptionMode": "balanced"
  }'

Use precision quando o fluxo priorizar precisao em vez de custo.

A resposta retorna data.task.transcriptId; use esse valor como TASK_ID ao consultar.

Modo	Melhor para
balanced	Transcricao rapida e economica para a maioria dos fluxos de producao.
precision	Transcricao de maior precisao quando a qualidade importa mais que o custo.

5. Consultar a tarefa

Consulte o endpoint da tarefa ate que status seja SUCCEEDED, FAILED ou CANCELED.

curl "https://api.videototext.dev/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $VTT_API_KEY"

Tarefas bem-sucedidas retornam texto da transcricao, campos publicos de tempo por trecho, timestamps por palavra, detalhes do arquivo de origem e creditos cobrados.