Inicio rápido

Esta guia recorre el flujo completo de la API: crear una carga, enviar el archivo multimedia, completar la carga, crear una tarea de transcripcion y consultar los resultados.

Visita Video To Text para gestionar tu cuenta, crear claves de API y volver al espacio de trabajo del producto.

Define la URL base de la API y la clave:

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

1. Crear una carga

Crea una URL de carga firmada para el archivo multimedia.

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"
  }'

La respuesta incluye los campos necesarios para los pasos siguientes:

{
  "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. Subir el archivo

Sube el archivo binario directamente a uploadUrl. Usa el mismo valor de Content-Type enviado al crear la carga.

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

3. Completar la carga

Completa la sesion de carga para que Video To Text pueda validar el objeto y crear un 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
  }'

La respuesta devuelve el assetId usado para crear una tarea de transcripcion.

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

4. Crear una tarea de transcripcion

Crea la tarea a partir del asset subido. El modo predeterminado es 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"
  }'

Usa precision cuando el flujo priorice la precision sobre el coste.

La respuesta devuelve data.task.transcriptId; usa ese valor como TASK_ID al consultar.

Modo	Ideal para
balanced	Transcripcion rapida y rentable para la mayoria de flujos de produccion.
precision	Transcripcion de mayor precision cuando la calidad importa mas que el coste.

5. Consultar la tarea

Consulta el endpoint de la tarea hasta que status sea SUCCEEDED, FAILED o CANCELED.

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

Las tareas correctas devuelven el texto de la transcripcion, campos publicos de tiempo por fragmento, marcas de tiempo por palabra, detalles del archivo de origen y creditos facturados.