Referência da API

Base URL:

https://api.videototext.dev

Envelope de resposta

Respostas bem-sucedidas usam:

{
  "data": {},
  "meta": {}
}

Erros usam Problem Details:

{
  "type": "VALIDATION_ERROR",
  "title": "Validation failed",
  "status": 400,
  "detail": "Invalid request",
  "errorCode": "VALIDATION_ERROR"
}

Modos de transcricao

Modo	Creditos	Observacoes
balanced	1 credito por minuto	Modo padrao
precision	2 creditos por minuto	Opcao de maior precisao

Status das tarefas

Status	Significado
QUEUED	A tarefa esta aguardando capacidade de processamento.
PROCESSING	A tarefa esta sendo transcrita.
SUCCEEDED	A transcricao esta pronta.
FAILED	A tarefa falhou e pode incluir showError.
CANCELED	A tarefa foi cancelada.

POST /v1/uploads

Crie uma URL de upload assinada.

Requisição:

{
  "filename": "meeting.mp4",
  "mimetype": "video/mp4"
}

Resposta:

{
  "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": {}
}

POST /v1/uploads/{uploadId}/operations/complete

Valide o objeto enviado, leia a duracao da midia e crie um asset.

Parametros de caminho:

Nome	Tipo	Descricao
uploadId	UUID	ID da sessao de upload retornado por POST /v1/uploads.

Requisição:

{
  "fileKey": "uploads/example.mp4",
  "fileUrl": "https://static.example.com/uploads/example.mp4",
  "filename": "meeting.mp4",
  "mimetype": "video/mp4",
  "fileSize": 10485760
}

Resposta:

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

Erros comuns incluem UPLOAD_SESSION_NOT_FOUND, UPLOAD_SESSION_EXPIRED, UPLOAD_SIZE_MISMATCH, UPLOAD_MIMETYPE_MISMATCH e UPLOAD_DURATION_UNREADABLE.

POST /v1/tasks

Crie uma tarefa de transcricao a partir de um asset enviado.

Para criacao de tarefas segura para repeticao, veja Idempotencia.

Requisição:

{
  "assetId": "00000000-0000-0000-0000-000000000000",
  "language": "Auto",
  "timestampMode": "CHUNK",
  "transcriptionMode": "balanced"
}

Campos:

Campo	Tipo	Obrigatorio	Observacoes
assetId	UUID	Sim	Asset retornado pela conclusao do upload.
language	string	Nao	O padrao e Auto. Idiomas suportados usam nomes em minusculas, como english, spanish ou chinese.
timestampMode	string	Nao	CHUNK ou WORD. O padrao e CHUNK.
transcriptionMode	string	Nao	Chave publica do modo: balanced ou precision. O padrao e balanced.

Resposta:

{
  "data": {
    "task": {
      "transcriptId": "00000000-0000-0000-0000-000000000000",
      "status": "QUEUED",
      "language": "Auto",
      "timestampMode": "CHUNK",
      "transcriptionMode": "balanced",
      "billedCredits": "1.500000000000"
    }
  },
  "meta": {
    "pollAfterMs": 1500
  }
}

As respostas de criação e detalhe da tarefa sempre incluem transcriptionMode com a chave pública de modo usada para cobrança e processamento do resultado.

GET /v1/tasks/{taskId}

Retorne o status atual da tarefa e os campos de resultado da transcricao necessarios para clientes.

Parametros de caminho:

Nome	Tipo	Descricao
taskId	UUID	data.task.transcriptId retornado por POST /v1/tasks.

Resposta:

{
  "data": {
    "task": {
      "transcriptId": "00000000-0000-0000-0000-000000000000",
      "status": "SUCCEEDED",
      "showError": null,
      "fullText": "Welcome to the meeting.",
      "chunks": [
        {
          "seq": 0,
          "startMs": 0,
          "endMs": 2200,
          "text": "Welcome to the meeting.",
          "speakerKey": null,
          "speakerName": null,
          "wordStartIndex": 0,
          "wordEndIndex": 1
        }
      ],
      "words": [
        {
          "text": "Welcome",
          "startMs": 0,
          "endMs": 600
        }
      ],
      "sourceDurationMs": 90400,
      "language": "Auto",
      "resultLanguage": "english",
      "timestampMode": "CHUNK",
      "transcriptionMode": "balanced",
      "billedCredits": "1.500000000000",
      "createdAt": "2026-06-06T09:00:00.000Z"
    }
  },
  "meta": {}
}