Référence API

Authentification

Utilisez votre clé API depuis Settings > API Keys. Les requêtes accèdent uniquement aux ressources de ce compte.

Formats pris en charge :

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

---

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 :

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 :

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 :

---

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 :

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 :

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

Familles MIME prises en charge :

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

Limites de stockage par plan :

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 :

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 :

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

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 :

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é

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 :

{
  "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.