# API y uso

URL base:
- `https://video.renderingvideo.com`

Flujo público:
- Usa `POST /api/preview` para crear una vista previa
- Usa `/t/:id` o `/preview/:id` como enlace de reproducción
- Los enlaces de vista previa caducan en 7 días
- No dependas de rutas internas no documentadas

## 1. API de enlace temporal

Endpoints externos:
- `POST /api/preview`
- `GET /api/temp/:id`
- `GET /t/:id`
- `GET /preview/:id`
- `GET /`

Comportamiento de los enlaces temporales:
- Los datos de vista previa se almacenan en KV
- La expiración por defecto es de 7 días
- La página de vista previa devuelta puede compartirse directamente con usuarios externos

## 2. `POST /api/preview`

Propósito:
- Enviar un esquema para vista previa
- Ejecutar la validación de la estructura de nivel superior
- Generar un enlace temporal de vista previa

### Encabezados de la solicitud

```http
Content-Type: application/json
```

### Cuerpo de la solicitud

Envía el JSON completo del esquema directamente como cuerpo de la solicitud.

Ejemplo mínimo:

```json
{
  "meta": {
    "version": "2.0.0",
    "width": 1920,
    "height": 1080,
    "fps": 30
  },
  "tracks": [
    {
      "clips": [
        {
          "type": "text",
          "start": 0,
          "duration": 3,
          "text": "Temporary Preview"
        }
      ]
    }
  ]
}
```

### Respuesta correcta

```json
{
  "success": true,
  "tempId": "uuid",
  "url": "/t/uuid",
  "viewerUrl": "/preview/uuid",
  "expiresIn": "604800 seconds (7 days)"
}
```

Campos de respuesta:
- `url`: página limpia del reproductor
- `viewerUrl`: variante de la página de vista previa
- `tempId`: identificador usado para leer después la configuración temporal

### Casos comunes de error

La solicitud puede fallar por:
- JSON no válido
- Falta de `meta` o `tracks` en el nivel superior
- Un cuerpo que no coincide con el `VideoSchema` actual

## 3. `GET /api/temp/:id`

Propósito:
- Leer el esquema detrás de un enlace temporal
- Permitir que tu aplicación inspeccione la configuración actual de vista previa

### Respuesta correcta

```json
{
  "success": true,
  "config": {
    "meta": {
      "version": "2.0.0",
      "width": 1920,
      "height": 1080,
      "fps": 30
    },
    "tracks": [
      {
        "clips": [
          {
            "type": "text",
            "start": 0,
            "duration": 3,
            "text": "Temporary Preview"
          }
        ]
      }
    ]
  }
}
```

Casos comunes de error:
- `id` no es un UUID válido
- El enlace temporal no existe
- El enlace temporal ha caducado

## 4. Páginas de vista previa

Los enlaces temporales exponen dos páginas de reproducción:
- `GET /t/:id`: página limpia del reproductor
- `GET /preview/:id`: variante de la página de vista previa

Si el enlace temporal ha caducado, esas páginas devuelven un mensaje de estado no válido.

- La API pública garantiza las URLs de vista previa, no los detalles internos de implementación del reproductor
- No dependas de rutas proxy de assets no documentadas, lógica de rewrite del lado del cliente o helpers internos de runtime

## 5. Flujo externo recomendado

Orden recomendado:
1. Construir `meta / assets / tracks`
2. Colocar medios reutilizables en `assets` siempre que sea posible
3. Referenciar medios mediante `$ref` dentro de los clips cuando corresponda
4. Enviar a `POST /api/preview`
5. Compartir el `/t/:id` o `/preview/:id` devuelto
6. Si más adelante hace falta, convertir la vista previa temporal en una tarea permanente mediante el flujo de tu aplicación

## 6. Recomendaciones de autoría

### Recomendación 1

Prefiere `$ref` para medios reutilizables en lugar de repetir URLs en varios clips.

### Recomendación 2

Si los subtítulos provienen de un servicio externo, una forma de respuesta estable es:

```json
{
  "words": [
    {
      "word": "hello",
      "punctuated_word": "Hello",
      "start": 0,
      "end": 0.4
    }
  ]
}
```

### Recomendación 3

No dependas de campos no documentados ni de detalles de implementación interna que no formen parte de la API pública.

## 7. Lista de depuración

Si la salida no coincide con lo esperado, revisa primero:
- ¿Sigues enviando un objeto `video` heredado en el nivel superior?
- ¿Tu esquema incluye valores válidos para `meta.version`, `meta.width`, `meta.height` y `tracks`?
- ¿Las URLs de medios remotos son accesibles directamente desde el entorno de reproducción?
- ¿El enlace temporal ya ha caducado?

## 8. Ejemplo de solicitud

```bash
curl -X POST https://video.renderingvideo.com/api/preview \
  -H "Content-Type: application/json" \
  -d @temp-preview.json
```

Más ejemplos: [Ejemplos](https://renderingvideo.com/docs/examples.md)