# API et utilisation

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

Flux public :
- Utilisez `POST /api/preview` pour créer un aperçu
- Utilisez `/t/:id` ou `/preview/:id` comme lien de lecture
- Les liens d'aperçu expirent au bout de 7 jours
- Ne vous appuyez pas sur des routes internes non documentées

## 1. API des liens temporaires

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

Comportement des liens temporaires :
- Les données d'aperçu sont stockées dans KV
- L'expiration par défaut est de 7 jours
- La page d'aperçu renvoyée peut être partagée directement avec des utilisateurs externes

## 2. `POST /api/preview`

Objectif :
- Soumettre un schéma pour aperçu
- Exécuter la validation de la structure de premier niveau
- Générer un lien d'aperçu temporaire

### En-têtes de requête

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

### Corps de requête

Envoyez le schéma JSON complet directement comme corps de requête.

Exemple minimal :

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

### Réponse en cas de succès

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

Champs de réponse :
- `url` : page lecteur épurée
- `viewerUrl` : variante de page d'aperçu
- `tempId` : identifiant utilisé pour relire plus tard la configuration temporaire

### Cas d'échec fréquents

La requête peut échouer à cause de :
- JSON invalide
- `meta` ou `tracks` manquant au niveau supérieur
- corps qui ne correspond pas au `VideoSchema` actuel

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

Objectif :
- Lire le schéma derrière un lien temporaire
- Permettre à votre application d'inspecter la configuration d'aperçu actuelle

### Réponse en cas de succès

```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"
          }
        ]
      }
    ]
  }
}
```

Cas d'échec fréquents :
- `id` n'est pas un UUID valide
- le lien temporaire n'existe pas
- le lien temporaire a expiré

## 4. Pages d'aperçu

Les liens temporaires exposent deux pages de lecture :
- `GET /t/:id` : page lecteur épurée
- `GET /preview/:id` : variante de page d'aperçu

Si le lien temporaire a expiré, ces pages renvoient un message d'état invalide.

- L'API publique garantit les URL d'aperçu, pas les détails internes de l'implémentation du lecteur
- Ne dépendez pas de chemins proxy d'assets non documentés, de logique de réécriture côté client ou d'helpers runtime internes

## 5. Flux externe recommandé

Ordre recommandé :
1. Construire `meta / assets / tracks`
2. Placer les médias réutilisables dans `assets` autant que possible
3. Référencer les médias via `$ref` dans les clips quand c'est pertinent
4. Soumettre à `POST /api/preview`
5. Partager le lien retourné `/t/:id` ou `/preview/:id`
6. Si nécessaire plus tard, convertir l'aperçu temporaire en tâche permanente via le flux de votre application

## 6. Recommandations de rédaction

### Recommandation 1

Préférez `$ref` pour les médias réutilisables au lieu de répéter des URLs dans plusieurs clips.

### Recommandation 2

Si les sous-titres proviennent d'un service externe, cette forme de réponse est stable :

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

### Recommandation 3

Ne vous appuyez pas sur des champs non documentés ou des détails d'implémentation interne qui ne font pas partie de l'API publique.

## 7. Checklist de débogage

Si la sortie ne correspond pas aux attentes, vérifiez d'abord :
- envoyez-vous encore un objet `video` hérité au niveau supérieur
- votre schéma inclut-il des valeurs valides pour `meta.version`, `meta.width`, `meta.height` et `tracks`
- les URLs de médias distants sont-elles directement accessibles par l'environnement de lecture
- le lien temporaire a-t-il déjà expiré

## 8. Exemple de requête

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

Autres exemples : [Exemples](https://renderingvideo.com/docs/examples.md)