# Référence API

## Authentification

Utilisez votre clé API depuis [Settings > API Keys](https://renderingvideo.com/settings/apikeys). Les requêtes accèdent uniquement aux ressources de ce compte.

Formats pris en charge :

| Méthode              | Format                         |
| -------------------- | ------------------------------ |
| Bearer Token         | `Authorization: Bearer sk-xxx` |
| Token Header         | `Authorization: Token sk-xxx`  |
| X-API-Key            | `X-API-Key: sk-xxx`            |
| Paramètre de requête | `?api_key=sk-xxx`              |

Rappel sécurité :

- n'exposez jamais votre clé API côté client
- effectuez toujours les appels API depuis votre serveur

---

## Vue d'ensemble des endpoints

| Méthode | Endpoint                          | Usage                                     |
| ------- | --------------------------------- | ----------------------------------------- |
| POST    | `/api/v1/video`                   | Créer une tâche vidéo permanente          |
| GET     | `/api/v1/video`                   | Lister les tâches vidéo                   |
| GET     | `/api/v1/video/:taskId`           | Lire les détails d'une tâche              |
| DELETE  | `/api/v1/video/:taskId`           | Supprimer une tâche vidéo                 |
| POST    | `/api/v1/video/:taskId/render`    | Déclencher un rendu                       |
| POST    | `/api/v1/upload`                  | Uploader des assets                       |
| GET     | `/api/v1/files`                   | Lister les fichiers                       |
| DELETE  | `/api/v1/files/:fileId`           | Supprimer un fichier                      |
| GET     | `/api/v1/credits`                 | Lire le solde de crédits                  |
| POST    | `/api/v1/preview`                 | Créer une preview temporaire              |
| GET     | `/api/v1/preview/:tempId`         | Lire la configuration de preview          |
| DELETE  | `/api/v1/preview/:tempId`         | Supprimer une preview                     |
| POST    | `/api/v1/preview/:tempId/convert` | Convertir une preview en tâche permanente |
| POST    | `/api/v1/preview/:tempId/render`  | Convertir une preview et lancer le rendu  |

---

## POST /api/v1/video

Crée une tâche vidéo permanente à partir de votre configuration. Cette opération ne démarre pas encore le rendu.

Champs importants :

| Champ      | Type   | Requis | Description                                             |
| ---------- | ------ | ------ | ------------------------------------------------------- |
| `config`   | object | Oui    | Schéma vidéo conforme au [JSON Schema](https://renderingvideo.com/docs/json-spec.md) |
| `metadata` | object | Non    | Métadonnées personnalisées attachées à la tâche         |

Champs de réponse les plus utiles :

- `taskId`
- `videoTaskId`
- `previewUrl`
- `viewerUrl`
- `configUrl`
- `status`
- `quality`
- `width`
- `height`
- `duration`

---

## GET /api/v1/video

Liste toutes les tâches vidéo du compte courant.

Paramètres de requête :

| Paramètre | Type    | Défaut | Description                    |
| --------- | ------- | ------ | ------------------------------ |
| `page`    | integer | 1      | Numéro de page                 |
| `limit`   | integer | 20     | Éléments par page, maximum 100 |
| `status`  | string  | -      | Filtre sur le dernier statut   |

La réponse contient une liste `tasks` et un objet `pagination`.

---

## GET /api/v1/video/:taskId

Récupère les détails complets d'une tâche vidéo donnée.

Champs de retour utiles :

- `taskId`
- `videoTaskId`
- `status`
- `videoUrl`
- `previewUrl`
- `viewerUrl`
- `configUrl`
- `costCredits`
- `createdAt`
- `completedAt`
- `metadata`

Valeurs de statut :

| Statut      | Signification                  |
| ----------- | ------------------------------ |
| `created`   | Tâche créée, rendu non démarré |
| `rendering` | Rendu en cours                 |
| `completed` | Rendu terminé avec succès      |
| `failed`    | Échec du rendu                 |

---

## DELETE /api/v1/video/:taskId

Supprime définitivement une tâche et les enregistrements de rendu locaux associés. L'API tente aussi de supprimer la tâche distante upstream.

Champs de réponse importants :

- `deleted`
- `remoteDeleted`
- `message`

Si la suppression upstream échoue, la suppression locale peut malgré tout réussir.

---

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

Déclenche ou redéclenche le rendu d'une tâche existante.

Corps de requête :

| Champ         | Type    | Requis | Défaut | Description                |
| ------------- | ------- | ------ | ------ | -------------------------- |
| `webhook_url` | string  | Non    | -      | URL de notification de fin |
| `num_workers` | integer | Non    | 5      | Nombre de workers de rendu |

Résultats possibles :

- un nouveau rendu avec `status: rendering`
- une réponse réutilisant un rendu déjà terminé avec `alreadyRendered: true`

Erreurs fréquentes :

- `NOT_FOUND`
- `ALREADY_RENDERING`
- `INSUFFICIENT_CREDITS`
- `RENDER_TRIGGER_FAILED`

---

## Webhooks

`webhook_url` est pris en charge sur :

- `POST /api/v1/video/:taskId/render`
- `POST /api/v1/preview/:tempId/render`

Cycle de fonctionnement :

1. votre `webhook_url` est enregistrée avec la tâche de rendu
2. le renderer upstream renvoie `completed` ou `failed`
3. le projet met d'abord à jour sa base locale
4. un `POST` est ensuite envoyé à votre `webhook_url`

Le payload transmis contient généralement :

- `taskId`
- `renderTaskId`
- `status`
- `videoUrl`
- `error`
- `timestamp`

Limites actuelles :

- seuls les événements `completed` et `failed` sont transmis
- `webhook_url` doit être une URL absolue valide
- il n'existe pas encore de signature webhook
- il n'existe pas encore de file de retry ni de journal de livraison

---

## POST /api/v1/upload

Permet d'uploader des images, vidéos et audios utilisables ensuite dans les configurations vidéo.

Champs de formulaire :

| Champ   | Type   | Requis | Description        |
| ------- | ------ | ------ | ------------------ |
| `file`  | File   | Non\*  | Fichier unique     |
| `files` | File[] | Non\*  | Plusieurs fichiers |

\*Au moins l'un de `file` ou `files` est requis.

Familles MIME prises en charge :

- `image/*`
- `video/*`
- `audio/*`

Limites de stockage par plan :

| Plan     | Limite |
| -------- | ------ |
| Free     | 512 MB |
| Starter  | 10 GB  |
| Standard | 20 GB  |
| Pro      | 50 GB  |

La réponse de succès contient `count` et une liste `assets`.

---

## GET /api/v1/files

Liste les fichiers uploadés pour le propriétaire courant de la clé API.

Paramètres de requête :

| Paramètre | Type    | Défaut | Description                 |
| --------- | ------- | ------ | --------------------------- |
| `page`    | integer | 1      | Numéro de page              |
| `limit`   | integer | 20     | Éléments par page           |
| `type`    | string  | -      | `image`, `video` ou `audio` |

La réponse contient `files` et `pagination`.

---

## DELETE /api/v1/files/:fileId

Supprime définitivement un fichier de la bibliothèque. L'objet stocké et l'enregistrement du fichier sont supprimés ensemble.

Champs de réponse utiles :

- `fileId`
- `deleted`
- `message`

---

## GET /api/v1/credits

Récupère le solde de crédits actuel du compte.

Réponse type :

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

---

## POST /api/v1/preview

Crée une preview temporaire sans consommer de crédits.

Règles importantes :

- le schéma vidéo complet est envoyé directement dans le corps de la requête
- les liens de preview sont valables **7 jours**
- la preview ne consomme **pas** de crédits
- la preview ne génère **pas** de fichier vidéo téléchargeable

Champs de réponse :

- `tempId`
- `previewUrl`
- `viewerUrl`
- `expiresIn`

---

## GET /api/v1/preview/:tempId

Lit la configuration derrière un lien de preview temporaire.

Champs de retour :

- `tempId`
- `config`

---

## DELETE /api/v1/preview/:tempId

Supprime un lien de preview temporaire.

Champs de retour :

- `tempId`
- `deleted`
- `message`

---

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

Clone une preview temporaire en tâche vidéo permanente. La preview temporaire reste utilisable.

Corps de requête optionnel :

| Champ      | Type   | Requis | Description                              |
| ---------- | ------ | ------ | ---------------------------------------- |
| `category` | string | Non    | Catégorie à associer à la nouvelle tâche |

Champs de retour les plus utiles :

- `converted`
- `taskId`
- `videoTaskId`
- `previewUrl`
- `viewerUrl`
- `configUrl`

---

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

Clone une preview temporaire en tâche permanente puis lance immédiatement le rendu.

Corps de requête :

| Champ         | Type    | Requis | Défaut | Description                       |
| ------------- | ------- | ------ | ------ | --------------------------------- |
| `category`    | string  | Non    | `api`  | Catégorie de la nouvelle tâche    |
| `webhook_url` | string  | Non    | -      | Webhook pour le résultat de rendu |
| `num_workers` | integer | Non    | 5      | Nombre de workers de rendu        |

Réponse de succès typique :

- `converted: true`
- `taskId`
- `renderTaskId`
- `status: rendering`
- `cost`
- `remainingCredits`
- `previewUrl`
- `viewerUrl`

---

## Calcul des crédits

La règle de coût est la suivante :

- **coût = durée de la vidéo en secondes × multiplicateur de qualité**

| Qualité | Côté court   | Multiplicateur |
| ------- | ------------ | -------------- |
| 720p    | <= 720px  | 1.0            |
| 1080p   | <= 1080px | 1.5            |
| 2K      | <= 1440px | 2.0            |

La qualité est déterminée automatiquement à partir de la plus petite dimension de la vidéo.

---

## Format des erreurs

Toutes les réponses d'erreur suivent ce format :

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

Codes d'erreur fréquents :

- `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`

## Évolutions des SDK et de l’API

`GET /api/v1/capabilities` expose version du schéma, types de clips/animations/transitions, qualités et fonctionnalités. Les anciens déploiements peuvent répondre 404.

La création accepte `title` (1–255 caractères), `category` (1–100, valeur par défaut `api`) et un objet `metadata`. Listes et détails incluent titre et catégorie. `category=all` inclut les tâches du site ; sans filtre, la catégorie reste `api`. `all` est réservé aux listes.

Conversion et rendu des aperçus acceptent `metadata` et `category`. `POST /api/v1/preview/:tempId/render` convertit et lance le rendu. Options : `webhook_url` et entier positif `num_workers` (5 par défaut). Sans corps, les valeurs par défaut sont utilisées. Les paramètres invalides renvoient `INVALID_REQUEST` (400), les schémas invalides `INVALID_CONFIG` (400).

Les aperçus authentifiés exposent des adresses absolues `previewUrl`, `playerUrl` et, si disponible, `viewerUrl`. Conservez `tempId` et `expiresIn`. La qualité dépend des dimensions du schéma ; aucune option quality distincte n’est acceptée.