Documentación

Documentación

Referencia de API

Referencia REST API de los principales endpoints RenderingVideo v1

Referencia de API

Autenticación

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

Formatos compatibles:

Método Formato
Bearer Token Authorization: Bearer sk-xxx
Token Header Authorization: Token sk-xxx
X-API-Key X-API-Key: sk-xxx
Query Parameter ?api_key=sk-xxx

Recordatorio de seguridad:

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

Resumen de endpoints

Método Endpoint Uso
POST /api/v1/video Crear una tarea de video permanente
GET /api/v1/video Listar tareas de video
GET /api/v1/video/:taskId Leer detalles de una tarea
DELETE /api/v1/video/:taskId Eliminar una tarea de video
POST /api/v1/video/:taskId/render Lanzar el renderizado
POST /api/v1/upload Subir assets
GET /api/v1/files Listar archivos
DELETE /api/v1/files/:fileId Eliminar un archivo
GET /api/v1/credits Consultar saldo de créditos
POST /api/v1/preview Crear una preview temporal
GET /api/v1/preview/:tempId Leer la configuración de preview
DELETE /api/v1/preview/:tempId Eliminar una preview
POST /api/v1/preview/:tempId/convert Convertir una preview en tarea permanente
POST /api/v1/preview/:tempId/render Convertir una preview y renderizarla

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:

Campo Tipo Obligatorio Descripción
config object Sí Esquema de video conforme al JSON Schema
metadata object No Metadatos personalizados adjuntos a la tarea

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:

Parámetro Tipo Por defecto Descripción
page integer 1 Número de página
limit integer 20 Elementos por página, máximo 100
status string - Filtra por el estado más reciente

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:

Estado Significado
created Tarea creada, render todavía no iniciado
rendering Render en curso
completed Render finalizado con éxito
failed Render fallido

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:

Campo Tipo Obligatorio Por defecto Descripción
webhook_url string No - URL para la notificación final
num_workers integer No 5 Número de workers de render

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:

Campo Tipo Obligatorio Descripción
file File No* Archivo único
files File[] No* Varios archivos

*Al menos uno de file o files es obligatorio.

Familias MIME compatibles:

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

Límites de almacenamiento por plan:

Plan Límite
Free 512 MB
Starter 10 GB
Standard 20 GB
Pro 50 GB

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:

Parámetro Tipo Por defecto Descripción
page integer 1 Número de página
limit integer 20 Elementos por página
type string - image, video o audio

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:

Campo Tipo Obligatorio Descripción
category string No Categoría asociada a la nueva tarea

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:

Campo Tipo Obligatorio Por defecto Descripción
category string No api Categoría de la nueva tarea
webhook_url string No - Webhook para el resultado del render
num_workers integer No 5 Número de workers de render

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
Calidad Lado corto Multiplicador
720p <= 720px 1.0
1080p <= 1080px 1.5
2K <= 1440px 2.0

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