Référence de l’API

Conventions

Chaque endpoint /v1/* requiert l’en-tête Authorization: Bearer sk_.... Les erreurs reviennent en JSON avec un indicateur error et un message :

{
  "error": true,
  "message": "length must be a positive multiple of 30 seconds, at most 360"
}

Les endpoints de génération sont limités à 20 requêtes par minute. Tous les autres partagent une limite de 200 par minute.

Créer un explicatif

Démarre une génération et renvoie 202 Accepted avec l’enregistrement en file. Interrogez récupérer un explicatif jusqu’à ce qu’il soit ready.

{
  "input": "Explain how DNS resolves a domain name",
  "length": "0:30",
  "aspect": "16:9",
  "voice": "sketchie:sulafat",
  "language": "en"
}

Renvoie l’enregistrement de l’explicatif : id, status, prompt, lengthSeconds, voice, language, aspect, videoUrl (null jusqu’à prêt) et sceneGraph (null jusqu’à généré). Un 400 revient pour un input vide sans source, une length mal formée, ou un aspect, preset, fillMode ou language invalide.

Récupérer un explicatif

Renvoie l’enregistrement complet : status courant, la videoUrl une fois ready, le sceneGraph modifiable, l’historique des versions (versions) et les chunks de scène de la version principale. Un id manquant renvoie 404.

Lister les explicatifs

Liste les explicatifs de la clé appelante, du plus récent. Limité au propriétaire de la clé. limit est borné de 1 à 100 (défaut 50). Renvoie des résumés légers (sans scene graph ni versions). Utilisez récupérer un explicatif pour l’enregistrement complet.

Modifier un explicatif

Le levier de modifiabilité. Transformez une instruction en langage naturel en un re-rendu ciblé. Seules les scènes concernées sont re-rendues, produisant une nouvelle version. Renvoie 202 avec la version en file. Interrogez récupérer un explicatif jusqu’à ce que la version principale soit ready. Cela s’ajoute à la vidéo existante, donc ne consomme pas un autre créneau de création de vidéo gratuite. Le premier re-rendu de chaque vidéo est gratuit. Les suivants utilisent les minutes du forfait payant, et les comptes gratuits sont invités à démarrer un forfait. L’explicatif doit déjà être ready (sinon 409).

{ "instruction": "Make the title scene shorter and warmer" }

Revenir à une version

Repointe la version principale vers une version prête antérieure et reflète son graphe et sa vidéo sur l’enregistrement. La cible doit être une version ready avec une vidéo (sinon 409).

{ "versionId": "..." }

Flux de statut en direct

Un flux Server-Sent Events (text/event-stream). Ouvrez une connexion et chaque transition de statut sur l’un de vos explicatifs arrive sous forme de frame event: status, pour mettre à jour un état "vidéo prête" à l’instant où le worker termine au lieu d’interroger. Le flux est limité au propriétaire de votre clé.

Voix

Le catalogue de voix de narration. L’optionnel ?language=<code> filtre sur les voix natives de cette langue. Renvoie voices (chacune avec un name convivial, l’id à passer comme voice, language, isDefault et une preview_url jouable) plus le default global. Voir Voix.

Langues

Les langues de narration prises en charge, sous la forme { code, label, native }. Chaque code est un language valide à la création. Voir Langues.

État du compte

Renvoie videosGenerated (à vie), l’image du compte et isAdmin. Requiert une authentification.

Statut de facturation

Requiert une authentification et renvoie 200 pour les comptes gratuits et payants. Un compte gratuit renvoie plan: "free" avec videoAllowance, videosUsed et videosRemaining. Un compte payant renvoie aussi planLabel, billingInterval, trialStatus, quotaMinutes, minutesUsedThisPeriod, minutesRemaining et bonusMinutes.

Config d’exécution et santé

Public. Renvoie { "authEnforced": true }. Un liveness check se trouve à GET /health.