# Referencia de API

## Autenticación

Use su API key de [Settings > API Keys](https://renderingvideo.com/settings/apikeys). Las solicitudes solo acceden a los recursos de esa cuenta.

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](https://renderingvideo.com/docs/json-spec.md) |
| `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:

```json
{
  "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:

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

## Mejoras de SDK y API

`GET /api/v1/capabilities` devuelve versión del esquema, tipos de clips/animaciones/transiciones, calidades y funciones disponibles. Versiones antiguas pueden responder 404.

La creación acepta `title` (1–255 caracteres), `category` (1–100, por defecto `api`) y un objeto `metadata`. Listas y detalles incluyen título y categoría. `category=all` incluye tareas de la web; sin filtro se mantiene `api`. `all` se reserva para listas.

Conversión y renderizado de vistas previas aceptan `metadata` y `category`. `POST /api/v1/preview/:tempId/render` convierte e inicia el renderizado. Opciones: `webhook_url` y entero positivo `num_workers` (por defecto 5). Sin cuerpo se usan valores predeterminados. Parámetros inválidos devuelven `INVALID_REQUEST` (400); esquemas inválidos, `INVALID_CONFIG` (400).

Las vistas previas autenticadas ofrecen `previewUrl` y `playerUrl` absolutas, y `viewerUrl` cuando existe. Conserve `tempId` y `expiresIn`. La calidad se deriva de las dimensiones del esquema; no se acepta otra opción quality.