Referencia de la API

Base URL:

https://api.videototext.dev

Envoltorio de respuesta

Las respuestas correctas usan:

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

Los errores usan Problem Details:

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

Modos de transcripcion

Modo	Creditos	Notas
balanced	1 credito por minuto	Modo predeterminado
precision	2 creditos por minuto	Opcion de mayor precision

Estados de tarea

Estado	Significado
QUEUED	La tarea esta esperando capacidad de procesamiento.
PROCESSING	La tarea se esta transcribiendo.
SUCCEEDED	La transcripcion esta lista.
FAILED	La tarea fallo y puede incluir showError.
CANCELED	La tarea fue cancelada.

POST /v1/uploads

Crea una URL de carga firmada.

Solicitud:

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

Respuesta:

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

Valida el objeto subido, lee la duracion del archivo multimedia y crea un asset.

Parametros de ruta:

Nombre	Tipo	Descripcion
uploadId	UUID	ID de la sesion de carga devuelto por POST /v1/uploads.

Solicitud:

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

Respuesta:

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

Los errores comunes incluyen UPLOAD_SESSION_NOT_FOUND, UPLOAD_SESSION_EXPIRED, UPLOAD_SIZE_MISMATCH, UPLOAD_MIMETYPE_MISMATCH y UPLOAD_DURATION_UNREADABLE.

POST /v1/tasks

Crea una tarea de transcripcion a partir de un asset subido.

Para crear tareas de forma segura ante reintentos, consulta Idempotencia.

Solicitud:

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

Campos:

Campo	Tipo	Obligatorio	Notas
assetId	UUID	Si	Asset devuelto al completar la carga.
language	string	No	El valor predeterminado es Auto. Los idiomas compatibles usan nombres en minusculas, como english, spanish o chinese.
timestampMode	string	No	CHUNK o WORD. El valor predeterminado es CHUNK.
transcriptionMode	string	No	Clave publica del modo: balanced o precision. El valor predeterminado es balanced.

Respuesta:

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

Las respuestas de creación y detalle de tareas siempre incluyen transcriptionMode con la clave pública del modo usada para facturación y procesamiento del resultado.

GET /v1/tasks/{taskId}

Devuelve el estado actual de la tarea y los campos de resultado de transcripcion que necesitan los clientes.

Parametros de ruta:

Nombre	Tipo	Descripcion
taskId	UUID	data.task.transcriptId devuelto por POST /v1/tasks.

Respuesta:

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