Référence API

Authentification

Toutes les requêtes API nécessitent une clé API. Vous pouvez en obtenir une depuis Settings > API Keys.

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