Documentation API

https://api.incarn.co

Chaque requête est authentifiée par une clé secrète, envoyée en Bearer token :

Authorization: Bearer ik_live_xxxxxxxxxxxxxxxxxxxxxxxx

Créez et révoquez vos clés depuis votre tableau de bord. La clé complète n'est affichée qu'une seule fois à la création : stockez-la en lieu sûr, nous n'en gardons qu'une empreinte et ne pouvons pas vous la remontrer. Gardez vos clés côté serveur, jamais dans un navigateur, une app mobile ou un dépôt public.

Chaque animation réussie consomme 1 crédit. Vos crédits proviennent de votre abonnement (rechargé chaque mois) ou de packs achetés à la demande. Une génération échouée est automatiquement remboursée.

Modèle prépayé : vous ne dépensez que ce que vous avez acheté, jamais de facture surprise. À court de crédits, l'API renvoie 402 ; rechargez depuis votre tableau de bord. Vous pouvez activer la recharge automatique (rachat d'un pack borné quand le solde passe sous un seuil) pour ne jamais être bloqué.

POST /v1/animations

Envoyez la photo source de deux façons au choix.

A. Fichier (multipart/form-data) — champ image, 15 Mo max.

curl -X POST https://api.incarn.co/v1/animations \
  -H "Authorization: Bearer ik_live_xxx" \
  -F "[email protected]" \
  -F "prompt=léger sourire, petit mouvement de tête"

B. URL (application/json) — champ image_url, http(s) public uniquement (les hôtes privés/loopback sont refusés).

curl -X POST https://api.incarn.co/v1/animations \
  -H "Authorization: Bearer ik_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://exemple.com/grand-mere.jpg","prompt":"léger sourire"}'

Paramètre optionnel prompt : une indication libre sur le mouvement (gardé subtil). Si les deux champs sont fournis, le fichier l'emporte.

Idempotence — ajoutez un en-tête Idempotency-Key pour rendre les retries sûrs : une requête répétée avec la même clé renvoie l'animation d'origine sans relancer de génération ni reconsommer de crédit.

Réponse (202/200), le traitement est asynchrone :

{
  "id": "clx...",
  "status": "processing",
  "video_url": null,
  "error": null,
  "created_at": "2026-08-10T09:12:00.000Z"
}

GET /v1/animations/{id}

Interrogez ce point jusqu'à ce que status passe à succeeded ou failed. Comptez 1 à 3 minutes, interrogez toutes les quelques secondes.

curl https://api.incarn.co/v1/animations/clx... \
  -H "Authorization: Bearer ik_live_xxx"

{
  "id": "clx...",
  "status": "succeeded",
  "video_url": "https://cdn.incarn.co/....mp4",
  "error": null,
  "created_at": "2026-08-10T09:12:00.000Z"
}

• processing — génération en cours.
• succeeded — terminé, video_url pointe le MP4.
• failed — échec, error explique, crédit remboursé.

Passez un webhook_url à la création pour être notifié à la fin du job au lieu d'interroger le statut. Nous POSTons le même corps que GET /v1/animations/:id dès que le job est succeeded ou failed.

curl -X POST https://api.incarn.co/v1/animations \
  -H "Authorization: Bearer ik_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://exemple.com/photo.jpg","webhook_url":"https://votre-app.com/incarn"}'

Chaque livraison est signée : l'en-tête X-Incarn-Signature vaut sha256=<hmac>, un HMAC-SHA256 du corps brut avec votre secret de signature (visible dans votre tableau de bord). Vérifiez-le avant de traiter l'événement.

// Node.js
import { createHmac, timingSafeEqual } from "crypto";
const expected =
  "sha256=" + createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(header));

La livraison est ré-essayée quelques fois. Le corps porte l'id du job : dédoublonnez à la réception si besoin.

La création d'animation est limitée à 10 requêtes/minute par compte (au-delà : 429). Un nombre de générations en parallèle s'applique aussi selon votre formule (2, 5 ou 15) ; au-delà : 429, réessayez quand une génération se termine.

• 400 — requête invalide (photo manquante, trop petite, ou pas une image).
• 401 — clé API absente ou invalide.
• 402 — plus de crédits : rechargez pour continuer.
• 404 — animation introuvable (identifiant inconnu).
• 429 — limite de débit ou de parallélisme dépassée.

Les erreurs renvoient un corps JSON avec un champ message. La vidéo est générée en pleine qualité (HD). L'étiquetage IA et la politique de filigrane à la rediffusion relèvent de l'intégrateur.

L'application, la base de données et le stockage des vidéos sont hébergés en Europe (Allemagne). La génération vidéo est réalisée par un partenaire IA hors UE : les photos source y sont envoyées pour le traitement puis supprimées. Écrivez-nous pour vos exigences de résidence des données.