Les routes

Les routes utiles pour construire une intégration. Elles demandent toutes la clé, sauf celles marquées publiques.

Le tarif — GET /api/pricing · publique

{"unit": "source_minute", "minutes_per_credit": 1.0,
 "price_per_minute_usd": 0.12, "currency": "USD",
 "rounding": "second", "minimum_minutes": 0.0,
 "retention_days": 7, "storage_mb_per_minute": 4.4,
 "live_monitor_max_hours": 12}

price_per_minute_usd peut valoir null : affichez alors l’unité sans annoncer de montant.

L’arrondi (rounding) et le minimum facturé (minimum_minutes) se lisent ici. Ne les recopiez pas en dur dans votre code : lisez-les à chaque fois.

L’estimation — POST /api/estimate

// requête
{ "url": "https://youtube.com/watch?v=…",
  "start": 600, "end": 1500, "with_heatmap": true }

Champ rendu	Sens
duration_seconds	durée totale de la source, ou null si elle n’a pas pu être lue
billable_minutes	minutes facturées — celles de la portion si une plage est donnée
estimated_cost_usd	le montant, ou null
range	la plage retenue, ou null
heatmap	marqueurs {start, end, intensity}, en secondes absolues

range peut différer de ce que vous avez demandé : une fin au-delà de la vidéo est ramenée à la fin de la vidéo. Affichez la plage retenue.

La courbe (heatmap) est donnée en secondes absolues, sur la vidéo entière, jamais recalée sur la plage. with_heatmap ajoute quelques secondes à la réponse : ne le demandez que si vous affichez la courbe.

Un lien vers un direct en cours répond 400, avec un detail qui commence par source_is_live: : un direct se suit avec le Live Monitor, pas avec une génération.

Lancer une génération — POST /api/process

{ "url": "…", "start": 600, "end": 1500,
  "instructions": "garde les passages où il explique un concept",
  "reframe_mode": "auto",        // auto | subject | disabled
  "aspect": "9:16",              // 9:16 | 1:1 | 16:9
  "language": "fr",
  "max_clips": 5,
  "clip_seconds": 45,
  "subtitles": true,
  "brand_template": "account" }

Accepte aussi un multipart/form-data avec un fichier. start/end ne s’appliquent qu’à une URL.

• max_clips est un plafond de 1 à 20, pas une commande : l’analyse garde les meilleurs moments et peut en rendre moins. 0 est refusé. Absent, aucun plafond autre que celui de votre offre.
• clip_seconds est la durée moyenne visée, de 14 à 180 secondes. Absent, une minute. Les clips s’en écartent d’environ 40 % dans un sens ou dans l’autre, pour ne pas couper un moment avant sa fin.
• subtitles force les sous-titres (true) ou les retire (false) pour cette génération. Absent, c’est le modèle de marque qui décide. N’envoyez le champ que pour vous écarter du modèle.

brand_template accepte trois formes :

Valeur	Ce qui s’applique
"account"	le modèle de marque par défaut du compte
"<id>"	ce modèle enregistré
{ … }	ce modèle, décrit en clair, pour cette génération seulement
absent	aucun habillage

Attention

Un identifiant qui ne correspond à aucun modèle du compte fait partir la génération sans habillage — il ne retombe pas sur le modèle par défaut. La réponse porte brand_template_applied : true si un modèle a bien été appliqué.

Plusieurs vidéos — POST /api/batch

Même corps, avec urls (1 à 20 liens) à la place de url. Les réglages s’appliquent à chaque vidéo du lot.

Suivre — GET /api/status/{job_id}

L’étape, la progression et, une fois la génération terminée, les clips. Interrogez toutes les quelques secondes : les clips arrivent ensemble, à la fin.

Chaque clip porte :

• signed_url (à préférer) et video_url — la vidéo ;
• cover_url / cover_signed_url — une vignette. Ces clés peuvent être absentes : testez leur présence plutôt que de lire un null ;
• viral_score — la note du clip, de 1 à 100, ou null s’il n’en a pas. null n’est pas 0.

Astuce

Utilisez la vignette pour afficher une liste de clips : elle pèse quelques dizaines de Ko, contre plusieurs dizaines de Mo pour la vidéo.

L’historique — GET /api/history

Rend {"jobs": [...], "failed": [...]}.

• jobs : les générations du compte qui ont produit des clips, avec les mêmes clés que status. La liste n’est ni paginée ni triée : triez de votre côté. Une génération en cours n’y figure pas encore.
• expired: true sur une génération : sa durée de conservation est passée, ses clips n’existent plus. Ne proposez ni lecture ni téléchargement.
• group : les segments d’une même surveillance de direct portent le même group.id, qui permet de les réunir. Traitez-le comme opaque.
• failed : les générations qui ont échoué sans rien produire — leur identifiant, leur date, leur lien source quand il existe, et reason, un message technique en anglais, à ne pas afficher tel quel. Au plus cinquante entrées, les plus récentes d’abord, dans la limite de la durée de conservation.

Le solde — GET /api/credits

{"balance": 1960, "reserved": 0, "unlimited": false,
 "allocated": 2000, "used": 40, "carried_over": 0, "plan": "studio",
 "email_verifie": true,
 "period_start": "…", "period_end": "…",
 "ledger": [{"at": "…", "delta": -40, "reason": "generation", "job_id": "…"}]}

balance = allocated − used + carried_over. carried_over est la dette reportée de la période précédente : négatif ou 0, jamais positif — voir Les crédits.

Trois points à connaître :

• unlimited: true n’est pas balance: 0. Un compte illimité n’a pas de plafond ; seul ce champ le dit.
• reserved vaut toujours 0. Rien n’est bloqué au lancement : le débit a lieu à la fin, au prorata de la durée réellement traitée.
• email_verifie: false explique un allocated: 0 sur l’offre gratuite : l’adresse n’est pas encore confirmée.

Un lien de téléchargement — POST /api/media/{job_id}/{index}/link

Rend {"url": "…", "expires_at": 1787707500} : une adresse signée, lisible sans compte, valable une heure. index est la position du clip dans la liste rendue par status.

Si vous transmettez ce lien, dites son échéance à qui le reçoit : passé une heure, il ne fonctionne plus.

Les offres — GET /api/plans · publique

Les offres, leurs crédits, leurs fonctions et leurs plafonds — les mêmes que sur la page des tarifs. Lisez les montants ici plutôt que de les écrire en dur.

Les autres routes

La configuration, le Live Monitor, la publication et les modèles de marque ont aussi des routes, utilisées par l’application. Leurs corps peuvent encore évoluer : elles ne sont pas documentées ici. Les routes de cette page, elles, ne changent pas sans préavis.