Referencia de API

Autenticación

Todas las solicitudes API requieren una API key. Puedes obtenerla en Settings > API Keys.

Formatos compatibles:

Recordatorio de seguridad:

• nunca expongas tu API key en código cliente
• realiza siempre las llamadas API desde tu servidor

Resumen de endpoints

POST /api/v1/video

Crea una tarea de video permanente a partir de tu configuración. Esta operación todavía no inicia el render.

Campos importantes:

Campos de respuesta más útiles:

• taskId
• videoTaskId
• previewUrl
• viewerUrl
• configUrl
• status
• quality
• width
• height
• duration

GET /api/v1/video

Lista todas las tareas de video de la cuenta actual.

Parámetros de consulta:

La respuesta contiene una lista tasks y un objeto pagination.

GET /api/v1/video/:taskId

Recupera los detalles completos de una tarea de video concreta.

Campos de retorno útiles:

• taskId
• videoTaskId
• status
• videoUrl
• previewUrl
• viewerUrl
• configUrl
• costCredits
• createdAt
• completedAt
• metadata

Valores de estado:

DELETE /api/v1/video/:taskId

Elimina de forma permanente una tarea y sus registros locales de render. La API también intenta eliminar la tarea remota upstream.

Campos de respuesta importantes:

• deleted
• remoteDeleted
• message

Si la eliminación upstream falla, la eliminación local puede seguir siendo correcta.

POST /api/v1/video/:taskId/render

Inicia o reinicia el render de una tarea existente.

Cuerpo de la solicitud:

Resultados posibles:

• un nuevo render con status: rendering
• una respuesta reutilizando un render ya terminado con alreadyRendered: true

Errores frecuentes:

• NOT_FOUND
• ALREADY_RENDERING
• INSUFFICIENT_CREDITS
• RENDER_TRIGGER_FAILED

Webhooks

webhook_url está disponible en:

• POST /api/v1/video/:taskId/render
• POST /api/v1/preview/:tempId/render

Flujo de funcionamiento:

1. tu webhook_url se guarda junto a la tarea de render
2. el renderer upstream devuelve completed o failed
3. el proyecto actualiza primero la base local
4. después envía un POST a tu webhook_url

El payload reenviado suele incluir:

• taskId
• renderTaskId
• status
• videoUrl
• error
• timestamp

Limitaciones actuales:

• solo se reenvían completed y failed
• webhook_url debe ser una URL absoluta válida
• todavía no existe firma de webhook
• todavía no existe cola de reintentos ni log de entrega

POST /api/v1/upload

Permite subir imágenes, videos y audios para usarlos después en configuraciones de video.

Campos de formulario:

*Al menos uno de file o files es obligatorio.

Familias MIME compatibles:

• image/*
• video/*
• audio/*

Límites de almacenamiento por plan:

La respuesta de éxito incluye count y una lista assets.

GET /api/v1/files

Lista los archivos subidos para el propietario actual de la API key.

Parámetros de consulta:

La respuesta incluye files y pagination.

DELETE /api/v1/files/:fileId

Elimina de forma permanente un archivo de la biblioteca. Se eliminan tanto el objeto almacenado como el registro del archivo.

Campos de respuesta útiles:

• fileId
• deleted
• message

GET /api/v1/credits

Recupera el saldo actual de créditos de la cuenta.

Respuesta típica:

{
  "success": true,
  "credits": 985,
  "currency": "credits"
}

POST /api/v1/preview

Crea una preview temporal sin consumir créditos.

Reglas importantes:

• el esquema de video completo se envía directamente en el body
• los enlaces de preview duran 7 días
• la preview no consume créditos
• la preview no genera un archivo descargable de video

Campos de respuesta:

• tempId
• previewUrl
• viewerUrl
• expiresIn

GET /api/v1/preview/:tempId

Lee la configuración detrás de un enlace temporal de preview.

Campos de retorno:

• tempId
• config

DELETE /api/v1/preview/:tempId

Elimina un enlace temporal de preview.

Campos de retorno:

• tempId
• deleted
• message

POST /api/v1/preview/:tempId/convert

Clona una preview temporal en una tarea de video permanente. La preview temporal sigue disponible.

Cuerpo opcional:

Campos de retorno más útiles:

• converted
• taskId
• videoTaskId
• previewUrl
• viewerUrl
• configUrl

POST /api/v1/preview/:tempId/render

Clona una preview temporal en una tarea permanente y lanza inmediatamente el render.

Cuerpo de la solicitud:

Respuesta de éxito típica:

• converted: true
• taskId
• renderTaskId
• status: rendering
• cost
• remainingCredits
• previewUrl
• viewerUrl

Cálculo de créditos

La regla de coste es:

• coste = duración del video en segundos × multiplicador de calidad

La calidad se determina automáticamente a partir de la dimensión más corta del video.

Formato de errores

Todas las respuestas de error siguen este formato:

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "additional context"
  }
}

Códigos de error frecuentes:

• MISSING_API_KEY
• INVALID_API_KEY
• INVALID_API_KEY_FORMAT
• API_KEY_INACTIVE
• USER_NOT_FOUND
• INVALID_REQUEST
• INVALID_CONFIG
• INSUFFICIENT_CREDITS
• NOT_FOUND
• ALREADY_RENDERING
• REMOTE_ERROR
• RENDER_TRIGGER_FAILED
• INTERNAL_ERROR