API Cabine.ai · v1 & v2

Documentation API

Offrez à vos clients un styliste et une cabine d'essayage, sur n'importe quelle plateforme : site sur mesure, WooCommerce, Magento, application mobile… Cette API donne accès aux mêmes services que nos modules Shopify et PrestaShop.

URL de base : https://cabine.ai/api · Format : JSON (UTF-8) · Toutes les requêtes en HTTPS.

Démarrage rapide

1. Créez une clé API dans votre espace : Compte › Clés API. Elle commence par vf_live_ (production) ou vf_test_ (tests : aucun crédit consommé, résultats d'exemple).
2. Vérifiez votre accès en consultant votre solde de crédits :

curl https://cabine.ai/api/v1/quota \
  -H "X-Api-Key: vf_test_xxxxxxxxxxxx"

3. Lancez un premier essayage avec une photo produit et une photo de personne :

curl -X POST https://cabine.ai/api/v1/generate \
  -H "X-Api-Key: vf_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_image_url": "https://maboutique.com/img/robe-lin.jpg",
    "user_photo_url":    "https://maboutique.com/uploads/client.jpg",
    "product_name":      "Robe en lin écru",
    "product_id":        42
  }'

La réponse contient result_url : l'image de votre client portant la robe. Vous avez votre premier essayage.

Authentification

Chaque requête porte votre clé dans l'en-tête X-Api-Key (ou Authorization: Bearer …).

Architecture recommandée

C'est l'architecture de nos modules officiels. Elle garde la clé secrète, vous permet d'appliquer vos propres règles (quotas par client, contrôle anti-abus) et de relier les essayages à vos paniers.

• Créez sur votre serveur une route par action (essayer, ouvrir le miroir, recommander, importer…) qui appelle l'API avec votre clé et renvoie la réponse au navigateur.
• Protégez ces routes : jeton CSRF de votre plateforme, limite de requêtes par visiteur (par exemple 10 recommandations par 10 minutes).
• Transmettez à Cabine.ai les identifiants utiles au suivi : product_id, cart_id, customer_id.

Crédits et limites

Les clés vf_test_ ne consomment aucun crédit. Les crédits se renouvellent à chaque échéance de votre forfait ; consultez-les avec GET /v1/quota.

Essayage photo HD

Votre client fournit une photo de lui ; vous fournissez la photo du produit. Cabine.ai compose une photo haute définition de votre client portant la pièce, en respectant sa silhouette et sa carnation.

{
  "success": true,
  "result_url": "https://cabine.ai/generation/a3f8…b2/download",
  "generation_id": 1042,
  "credits_used": 1,
  "credits_remaining": 163,
  "processing_time_ms": 21400
}

Suivre un essayage

Partager un essayage

Consulter son solde

{
  "success": true,
  "plan": "Boutique", "plan_slug": "boutique",
  "credits_total": 700, "credits_used": 137, "credits_bonus": 0,
  "credits_remaining": 563, "usage_percent": 20, "renews_at": "2026-11-01"
}

Miroir vivant

Via sa webcam, votre client se voit porter la pièce en temps réel : il tourne, s'avance, recule. La session dure 20 secondes et coûte 2 crédits. Le meilleur usage, celui de nos modules : afficher le miroir pendant la préparation de la photo HD, que votre client découvre à la fin (voir la recette).

Le flux vidéo circule directement entre le navigateur et le service temps réel de Cabine.ai ; votre serveur ouvre la session et en suit le déroulement. Côté navigateur, utilisez le SDK Cabine Live :

<!-- Module ES, à charger à la demande -->
const { CabineLive } = await import('https://cabine.ai/sdk/live/v1/cabine-live.js');

Ouvrir une session

{
  "success": true,
  "session_id": 8812,
  "duration_s": 20,
  "credits": 2,
  "connect_timeout_s": 20,
  "expiresAt": "2026-10-07T09:41:12Z",
  "session": "cl1.GEAFD1ZLEw5yGlgVBzFM…"
}

Suivi de session

Personal Shopper

À partir d'une photo et de quelques réponses (style, budget, type de pièce), Cabine.ai lit la colorimétrie, la silhouette et la corpulence de votre client, puis classe les looks de votre catalogue selon leur compatibilité avec lui. Vos looks et vos questions se gèrent dans votre espace (Personal Shopper) ou s'alimentent par l'import de catalogue.

1. Configuration : vérifiez la disponibilité et récupérez les questions à poser.
2. Recommandation (gratuite) : envoyez la photo et les réponses ; recevez le look n° 1, les alternatives classées, la raison du choix et un selection_id valable 15 minutes.
3. Essayage (1 crédit) : générez la photo HD de n'importe quel look de la recommandation. Nos modules le font automatiquement pour le look n° 1 : votre client se découvre directement dans le look.

Configuration

{
  "success": true,
  "enabled": true,            // inclus dans le forfait ET au moins un look publié
  "tryon_enabled": true,      // crédits disponibles pour l'essayage
  "published_looks": 124,
  "questions": [
    { "id": 3, "label": "Quel style vous ressemble ?", "type": "intent",
      "answers": [ { "id": 11, "label": "Chic intemporel" }, { "id": 12, "label": "Casual" } ] },
    { "id": 4, "label": "Votre budget pour ce look ?", "type": "budget", "answers": [ … ] }
  ]
}

Recommandation

{
  "success": true,
  "selected_look": {
    "id": 57, "name": "Blouse rouille & jupe midi", "image_url": "https://…",
    "match_score": 0.94, "styling_advice": "Le rouille près du visage réchauffe votre teint.",
    "total_price": 158.0, "currency": "EUR",
    "products": [ { "name": "Blouse col V", "price": 69, "product_url": "https://…", "image_url": "https://…" } ]
  },
  "alternatives": [ { "id": 61, "name": "Robe vert forêt", "match_score": 0.88, … } ],
  "why": {
    "profile": ["Automne profond", "Silhouette en A"],
    "reasons": [ { "label": "Harmonie colorimétrique", "text": "…" } ]
  },
  "selection_id": "sel_4f0c…",
  "selection_ttl": 900,
  "tryon_enabled": true
}

Essayer un look

{ "success": true, "generation_id": 2210,
  "tryon": { "status": "completed", "image_url": "https://…" } }

Suivre l'essayage

Importer des produits

Envoyez vos produits depuis votre base : Cabine.ai télécharge leurs photos en pleine définition et caractérise chaque vêtement (saisons colorimétriques, morphologies et corpulences qu'il flatte, style, occasion). Chaque produit devient un look du Personal Shopper.

{ "success": true, "batch_id": 318, "looks": 24,
  "follow_url": "https://cabine.fit/account/personal-shopper/import/318" }

Conversions

Recette · Bouton « Essayer » sur la fiche produit

1. Un bouton ouvre une fenêtre ; le client choisit une photo produit et importe sa photo.
2. Le navigateur redresse et réduit la photo (2 048 px, JPEG) puis l'envoie à votre serveur.
3. Votre serveur appelle /v1/generate avec la photo, l'image produit et vos identifiants (product_id, cart_id).
4. Affichez le résultat avec la mention « Généré par IA », un bouton « Ajouter au panier » et le partage.

<?php // Votre route serveur — exemple PHP générique
$payload = [
    'user_photo_b64'    => $_POST['photo'],                // envoyé par votre page
    'product_image_url' => $product->getImageUrl('large'), // votre catalogue
    'product_name'      => $product->getName(),
    'product_id'        => $product->getId(),
    'cart_id'           => $cart->getId(),
];
$ch = curl_init('https://cabine.ai/api/v1/generate');
curl_setopt_array($ch, [
    CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 180,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('CABINE_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = json_decode(curl_exec($ch), true);
header('Content-Type: application/json');
echo json_encode(['ok' => $response['success'] ?? false, 'image' => $response['result_url'] ?? null]);

Recette · Miroir vivant puis photo HD

L'expérience de nos modules : le miroir occupe les 20 secondes de préparation de la photo HD.

1. Le client importe sa photo et lance l'essayage : votre page appelle votre route « essayage HD » et, en parallèle, votre route « ouvrir le miroir ».
2. Votre serveur ouvre la session (/v2/live/session) et renvoie l'objet au navigateur, avec vos started_url / ended_url.
3. Le navigateur active la webcam, prépare le SDK, puis révèle le miroir avec son décompte.
4. À la fin du miroir (ou sur « Passer »), affichez la photo HD, prête entre-temps.

// Navigateur
const stream  = await navigator.mediaDevices.getUserMedia({ video: { facingMode: 'user' }, audio: false });
const session = await fetch('/cabine/live-open', { method: 'POST', body: formData }).then(r => r.json());
const { CabineLive } = await import('https://cabine.ai/sdk/live/v1/cabine-live.js');

const live = new CabineLive({
  video: document.querySelector('#mirror'),
  api: {
    liveStarted: (url) => fetch(url, { method: 'POST', keepalive: true }),
    liveEnded:   (url, reason, ms) => navigator.sendBeacon(url, JSON.stringify({ reason, duration_ms: ms })),
  },
});
const ready = await live.prepare({
  token: session,                       // réponse de votre serveur (+ started_url / ended_url)
  stream,
  referenceUrl:  product.images[0],     // photo du produit
  referenceUrls: product.images.slice(1),
  prompt: 'Dress the person in the garment shown: ' + product.name,
  onEnded: () => showHdResultWhenReady(),
});
if (ready) live.reveal({ onTick: (s) => countdown.textContent = s + ' s' });
else showHdResultWhenReady();          // miroir indisponible : crédits rendus, on passe à la photo HD

Recette · Bulle Personal Shopper

1. Au chargement de vos pages, votre serveur lit /v2/stylist/config (en cache) et n'affiche la bulle que si enabled.
2. Fenêtre : photo du client, puis questions une par une, chacune pouvant être passée.
3. Votre serveur appelle /v2/stylist/match (limitez à 10 demandes par visiteur et par 10 minutes).
4. Affichez le look n° 1 avec son conseil et le bloc « Pourquoi ce look vous va » (why), puis les alternatives.
5. Recommandé : lancez aussitôt /v2/stylist/tryon pour le look n° 1. Affichez la photo du client avec « Nous vous habillons… », puis remplacez-la par le résultat : votre client se découvre dans le look. Les alternatives gardent leurs photos produit et un bouton « L'essayer sur moi ».
6. Pour chaque pièce de votre boutique : « Ajouter » (votre panier) et « Essayer » (votre fiche produit, cabine ouverte).

Recette · Synchroniser le catalogue

1. Dans votre administration, proposez des filtres (catégorie, couleur, recherche) et une sélection de 50 produits au plus.
2. Pour chaque produit, construisez l'objet attendu : lien, nom, prix TTC, devise, catégorie, marque, description courte et photos d'origine.
3. Envoyez le lot à /v2/looks/import et affichez le lien de suivi.

// Exemple WooCommerce (PHP) — un produit par couleur
$products = [];
foreach ($selectedIds as $id) {
    $p = wc_get_product($id);
    $images = array_filter(array_map('wp_get_attachment_url',
        array_merge([$p->get_image_id()], $p->get_gallery_image_ids())));
    $products[] = [
        'url'          => get_permalink($id),
        'name'         => $p->get_name(),
        'price'        => (float) wc_get_price_including_tax($p),
        'currency'     => get_woocommerce_currency(),
        'category_raw' => wp_strip_all_tags(wc_get_product_category_list($id)),
        'description'  => wp_strip_all_tags($p->get_short_description()),
        'external_id'  => 'woo:' . $id,
        'images'       => array_slice(array_values($images), 0, 4),
    ];
}
$res = wp_remote_post('https://cabine.ai/api/v2/looks/import', [
    'headers' => ['X-Api-Key' => CABINE_API_KEY, 'Content-Type' => 'application/json'],
    'body'    => wp_json_encode(['source' => 'woocommerce', 'products' => $products]),
    'timeout' => 60,
]);

Erreurs

Toute erreur suit le même format : { "success": false, "error": "code", "message": "Description lisible" }. Affichez un message adapté à votre client à partir du code, jamais le message brut.

Bonnes pratiques

Photos

• Redressez la photo avant l'envoi. Les photos prises au téléphone sont souvent enregistrées « couchées » avec une simple indication d'orientation : redessinez-les dans le bon sens (par exemple createImageBitmap(file, { imageOrientation: 'from-image' }) puis un canvas), au format JPEG, 2 048 px au plus.
• Photo produit : la meilleure définition disponible, la pièce bien visible, sans texte incrusté.
• Photo client : de face, en pied ou à mi-corps, bonne lumière, fond simple.

Fiabilité

• Délais d'attente serveur : 180 s pour un essayage, 100 s pour une recommandation, 60 s pour un import.
• En cas d'expiration, suivez l'essayage par sa route de statut plutôt que de le relancer : vous éviterez un double débit.
• Mettez en cache la configuration du Personal Shopper (5 minutes).

Sécurité

• Clé API uniquement côté serveur, dans une variable d'environnement.
• Jeton CSRF et limite de requêtes sur chacune de vos routes.
• Ne transmettez jamais de données sans rapport avec l'essayage (adresse, paiement…).

Données personnelles

• La photo du client sert à l'analyse et à l'essayage ; elle n'est pas conservée pour la recommandation, et les résultats d'essayage ne restent accessibles que pendant une durée limitée.
• L'historique des recommandations (looks proposés, réponses, explication) est conservé 90 jours, sans photo.
• Chaque essayage affiché doit porter une mention indiquant qu'il est généré par intelligence artificielle et peut différer légèrement du vêtement réel.
• Informez vos clients dans votre politique de confidentialité ; un modèle de clause est disponible sur demande.

Historique