Démarrer avec l'API

L’API de ClipHeat est celle que l’application utilise : tout ce que vous faites depuis l’écran — estimer une vidéo, lancer une génération, suivre son avancée, récupérer les clips — se fait aussi depuis un script.

Adresse de base : https://clipheat.app/api · Format : JSON en entrée et en sortie (sauf le téléversement d’un fichier, en multipart/form-data).

1. Créer une clé

Dans l’application : Réglages → Clés d’API → Créer une clé.

La clé commence par ch_.
Elle n’est affichée qu’une fois. Copiez-la tout de suite dans un gestionnaire de secrets : ClipHeat ne la conserve pas en clair et ne peut pas vous la remontrer. Perdue, elle se révoque et se remplace.
Sur l’offre gratuite, l’adresse e-mail du compte doit être vérifiée avant de créer une clé. Sinon la création répond 403 avec un detail qui commence par email_not_verified:. Le lien de vérification est dans l’e-mail de bienvenue et se renvoie depuis les réglages.

2. S’authentifier

Chaque requête porte la clé dans un de ces en-têtes :

curl https://clipheat.app/api/credits \
  -H "X-API-Key: ch_votre_cle"

# équivalent
curl https://clipheat.app/api/credits \
  -H "Authorization: Bearer ch_votre_cle"

Aucun autre en-tête n’est nécessaire. La clé agit au nom de votre compte : mêmes crédits, mêmes projets, mêmes limites que dans l’application.

3. Vérifier que tout est branché

curl -s https://clipheat.app/api/credits -H "X-API-Key: ch_votre_cle"

{
  "balance": 1960,
  "allocated": 2000,
  "used": 40,
  "unlimited": false,
  "plan": "studio",
  "email_verifie": true,
  "period_end": "2026-10-26T13:54:07+00:00"
}

Un 200 : la clé est bonne. Un 401 ou un 403 : la clé manque, est mal recopiée, a expiré ou a été révoquée.

4. Une génération de bout en bout

Estimer (facultatif, sans rien débiter)

curl -s https://clipheat.app/api/estimate \
  -H "X-API-Key: ch_votre_cle" -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID", "start": 600, "end": 1500}'

La réponse donne la durée de la source, les minutes facturées (celles de la portion si vous donnez start/end, en secondes) et le montant estimé. La plage réellement retenue revient dans range : c’est elle qu’il faut afficher.

Lancer

curl -s https://clipheat.app/api/process \
  -H "X-API-Key: ch_votre_cle" -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID",
       "language": "fr", "max_clips": 5, "aspect": "9:16"}'

La réponse porte un job_id. max_clips est un plafond (1 à 20), pas une commande : une vidéo calme peut rendre moins de clips. Pour envoyer un fichier plutôt qu’une URL, postez-le en multipart/form-data.

Suivre

curl -s https://clipheat.app/api/status/JOB_ID -H "X-API-Key: ch_votre_cle"

Donne l’étape en cours, la progression et, une fois la génération terminée, la liste des clips avec leur titre, leur note, leurs bornes, video_url et, quand elle existe, une vignette (cover_url). Interrogez toutes les quelques secondes, pas plus vite : les clips sont livrés ensemble, à la fin.

Récupérer ou partager un clip

curl -s -X POST https://clipheat.app/api/media/JOB_ID/0/link \
  -H "X-API-Key: ch_votre_cle"

Rend {"url": "…", "expires_at": 1790000000} : une adresse de téléchargement signée, lisible sans compte, valable une heure. Le 0 est l’index du clip dans la liste renvoyée par status.

Le détail de chaque route — tous les champs, l’historique, les modèles de marque — est dans Les routes.

5. Les erreurs

Toute erreur renvoie un JSON avec un champ detail.

Code	Ce que ça veut dire
`400`	requête mal formée
`401` / `403`	clé absente, invalide ou révoquée — ou action non incluse dans l’offre (`detail` commence alors par `plan_feature_required:`)
`402`	crédits insuffisants pour cette durée
`404`	ressource introuvable pour ce compte — un identifiant d’un autre compte répond de la même façon
`409`	conflit : l’état de la ressource ne permet pas l’action (déjà en cours, déjà publiée…)
`422`	un champ est hors de ses bornes ; `detail` dit lequel
`429`	limite de débit atteinte — réessayez plus tard
`5xx`	incident de notre côté ou chez un fournisseur — réessayez avec un délai croissant

Quand un detail commence par un code suivi de : (email_not_verified:, plan_feature_required:…), c’est ce code qu’un script doit lire ; la phrase qui suit est destinée à un humain et peut changer.

Une valeur que ClipHeat ne peut pas déterminer est renvoyée à null, jamais à 0 : testez null avant d’afficher un montant ou une durée.

6. Les limites de débit

Chaque route a sa propre réserve de requêtes, par client. Au-delà : 429.

Route	Réserve	Recharge
`POST /api/process`	20	20 / min
`POST /api/batch`	10	10 / min
`POST /api/estimate`	20	20 / min
`POST /api/compose`	30	30 / min
`POST /api/publish`	30	30 / min
`POST /api/smartcut`, `/api/reframe`, `/api/edit-ai`	20	20 / min
`POST /api/media/{job_id}/{index}/link`	60	1 / s
`POST /api/auth/keys`	10	10 / min

POST /api/estimate interroge la plateforme source à chaque appel : estimez une fois par vidéo, puis faites vos calculs localement avec les champs de tarif renvoyés. Sur /api/edit-ai, un 429 signifie que le quota quotidien est atteint.

7. Bonnes pratiques

Gardez la clé côté serveur. Jamais dans une application mobile, une page web ou un dépôt de code : quiconque la lit agit en votre nom.
Une clé par usage (un script, une intégration) : vous pourrez en révoquer une sans casser les autres.
Réessayez avec un délai croissant sur 429 et 5xx, jamais en boucle serrée.
Ne relancez pas une génération en cas de doute : consultez d’abord son status. Relancer la même vidéo consomme de nouveaux crédits.

Et ensuite

Les routes — chaque route, ses champs et ses réponses.
Sécurité des clés — portée, durée de vie, révocation.
Serveur MCP — piloter ClipHeat depuis un assistant (Claude, Cursor…).