API Reference

Documentation API

API REST pour intégrer la cabine d'essayage virtuel IA dans vos boutiques e-commerce, et tracker les conversions générées.

Authentification

Toutes les requêtes nécessitent une clé API dans l'en-tête HTTP. Générez votre clé depuis Mon compte → Clés API. La même clé fonctionne pour V1 et V2.

Via l'en-tête X-Api-Key (recommandé)

X-Api-Key: vf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Via Authorization Bearer

Authorization: Bearer vf_live_xxxxxxxxxxxxxxxxxxxxxxxx

Gestion des erreurs

Toutes les réponses d'erreur suivent ce format :

{
  "success": false,
  "error":   "error_code",
  "message": "Description lisible en français"
}

Génération d'essayage V1

curl -X POST https://cabine.ai/api/v1/generate \
  -H "X-Api-Key: vf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_image_url": "https://maboutique.com/img/robe.jpg",
    "user_photo_url":    "https://maboutique.com/uploads/client.jpg",
    "product_id":         42,
    "cart_id":            67890,
    "customer_id":        12345
  }'

curl -X POST https://cabine.ai/api/v1/generate \
  -H "X-Api-Key: vf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_image_b64": "data:image/jpeg;base64,/9j/4AAQ...",
    "user_photo_b64":    "data:image/jpeg;base64,/9j/4AAQ...",
    "product_id":         42,
    "cart_id":            67890,
    "customer_id":        12345
  }'

curl -X POST https://cabine.ai/api/v1/generate \
  -H "X-Api-Key: vf_live_xxx" \
  -F "product_image=@/chemin/robe.jpg" \
  -F "user_photo=@/chemin/client.jpg" \
  -F "product_id=42" \
  -F "cart_id=67890" \
  -F "customer_id=12345"

curl -X POST https://cabine.ai/api/v1/generate \
  -H "X-Api-Key: vf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_image_b64": "data:image/jpeg;base64,/9j/4AAQ...",
    "user_photo_b64":    "data:image/jpeg;base64,/9j/4AAQ...",
    "category":           "robe courte",
    "prompt_type":        "universe",
    "product_name":       "Robe courte en soie rouge collection été",
    "product_id":         42,
    "cart_id":            67890
  }'

curl -X POST https://cabine.ai/api/v1/generate \
  -H "X-Api-Key: vf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_image_b64": "data:image/jpeg;base64,/9j/4AAQ...",
    "user_photo_b64":    "data:image/jpeg;base64,/9j/4AAQ...",
    "category":           "t-shirt enfant",
    "prompt_type":        "thematic",
    "product_name":       "T-shirt enfant dinosaures collection Jurassic",
    "product_id":         142
  }'

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

Prompts & catégories nouveau

cabine.ai permet d'utiliser des prompts spécialisés, configurés par catégorie de produit et par type de rendu, pour obtenir des résultats bien plus pertinents qu'avec un prompt générique. Les prompts sont gérés depuis votre back-office et appliqués automatiquement selon les informations que vous envoyez à l'API.

Principe de fonctionnement

À chaque appel à POST /generate, cabine.ai applique cette logique de priorité :

1. Si category ou product_name est fourni : recherche d'une catégorie correspondante via matching intelligent. Si un prompt actif existe pour ce couple (catégorie × type), il est utilisé.
2. Sinon, le champ prompt fourni par le client est utilisé (ancien comportement).
3. Sinon, le prompt haute-fidélité par défaut de cabine.ai est utilisé.

Les trois types de prompts

Matching intelligent des catégories

Vous n'avez pas besoin de connaître les slugs internes de cabine.ai. Envoyez simplement le libellé tel qu'il apparaît dans votre catalogue — le matcher trouve la meilleure correspondance grâce à un algorithme local (mots-clés, tokens, détection de genre) :

Catégories disponibles par défaut

cabine.ai fournit un catalogue initial qui couvre la majorité des cas e-commerce mode & accessoires :

• robe_longue
• robe_courte
• robe_mariee
• robe_couture
• jupe
• pantalon
• short_homme
• short_femme
• t_shirt
• chemise
• pull
• veste
• manteau
• casquette
• bonnet
• chapeau
• lunettes_soleil
• lunettes_vue
• chaussures
• sac
• maillot_bain

Besoin d'une catégorie supplémentaire (ex : bijouterie, montres, lingerie…) ? Contactez support@cabine.ai.

Gérer vos propres prompts

Les comptes Scale et Enterprise peuvent créer leurs propres prompts personnalisés depuis le back-office cabine.ai, section Prompts. Chaque prompt est lié à une catégorie et à un type, versionné automatiquement à chaque modification, avec historique et restauration en un clic.

Exemple complet — flux PrestaShop avec catégorie

// Récupération du produit + catégorie CMS côté PrestaShop
$product      = new Product((int) Tools::getValue('id_product'));
$categoryName = Category::getLinkRewrite($product->id_category_default, Context::getContext()->language->id);

$payload = json_encode([
    'product_image_b64' => 'data:image/jpeg;base64,' . base64_encode(file_get_contents($productImagePath)),
    'user_photo_b64'    => 'data:image/jpeg;base64,' . base64_encode(file_get_contents($userPhotoTmpPath)),
    'category'          => $categoryName,              // "robe-longue", "t-shirt-homme"…
    'prompt_type'       => 'universe',                // ou 'mirror'
    'product_name'      => $product->name[Context::getContext()->language->id],
    'product_id'        => (int) $product->id,
    'cart_id'           => (int) Context::getContext()->cart->id,
    'customer_id'       => (int) Context::getContext()->customer->id,
]);

Enregistrement de conversion V1

curl -X POST https://cabine.ai/api/v1/conversion \
  -H "X-Api-Key: vf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id":    "PS-00012345",
    "product_id":  42,
    "cart_id":     67890,
    "customer_id": 12345,
    "metadata": {
      "amount":   89.90,
      "currency": "EUR",
      "sku":      "ROBE-BLEU-M"
    }
  }'

{
  "success":               true,
  "conversion_id":         58,
  "linked_generation_id":  1042,
  "already_recorded":      false
}

{
  "success":               true,
  "conversion_id":         58,
  "linked_generation_id":  1042,
  "already_recorded":      true
}

// À appeler depuis le hook de confirmation de commande
public function hookActionOrderStatusPostUpdate($params)
{
    $order  = $params['order'];
    $status = $params['newOrderStatus'];

    // Ne déclencher que sur commandes validées/payées
    if (!in_array($status->id, [2, 12])) return;

    foreach ($order->getProducts() as $product) {
        $payload = json_encode([
            'order_id'    => (string) $order->reference,
            'product_id'  => (int) $product['product_id'],
            'cart_id'     => (int) $order->id_cart,
            'customer_id' => (int) $order->id_customer,
            'metadata'    => [
                'amount'   => (float) $order->total_paid,
                'currency' => Context::getContext()->currency->iso_code,
                'sku'      => $product['reference'],
            ],
        ]);

        file_get_contents('https://cabine.ai/api/v1/conversion', false,
            stream_context_create(['http' => [
                'method'  => 'POST',
                'header'  => "X-Api-Key: vf_live_xxx\r\nContent-Type: application/json",
                'content' => $payload,
                'timeout' => 5,
                'ignore_errors' => true, // Ne pas bloquer la confirmation commande
            ]])
        );
    }
}

Consulter son quota V1

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

{
  "success":            true,
  "plan":               "Growth",
  "plan_slug":          "growth",
  "credits_total":      200,
  "credits_used":       37,
  "credits_bonus":      0,
  "credits_remaining":  163,
  "usage_percent":      18,
  "renews_at":          "2025-02-01"
}

Modèles disponibles V1

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

{
  "success": true,
  "models": [
    {
      "id":                     "gemini-3-pro-image-preview",
      "label":                  "Flash Image — défaut ✅",
      "credits_per_generation": 1,
      "available":             true
    }
  ]
}

Look Try-On — Personal Shopper IA V2

L'API V2 propose un essayage virtuel d'un Look complet (tenue entière coordonnée par la marque) avec recommandation stylistique automatique. Le client envoie uniquement sa photo : Cabine.ai analyse son profil stylistique, sélectionne le Look le plus adapté parmi ceux publiés par le marchand, et génère l'essayage.

Pipeline complet

Coût et architecture

L'appel V2 coûte 1 crédit, comme un essayage /api/v1/generate. L'analyse stylistique du profil et le matching des Looks ne consomment pas de crédit supplémentaire — seule la génération photoréaliste finale est facturée, exactement comme en V1. En interne, la V2 délègue la génération d'image au même orchestrateur que la V1 (file d'attente asynchrone, persistance, gestion d'erreur, stockage), ce qui garantit un comportement et une fiabilité identiques entre les deux endpoints.

Essayage d'un Look V2

# 1er appel — recommandation
curl -X POST https://cabine.ai/api/v2/look-tryon \
  -H "Authorization: Bearer VOTRE_CLE" \
  -F user_photo=@client.jpg

# Réponse → alternatives: [{ "id": 47, ... }, { "id": 52, ... }]

# 2e appel — le client veut essayer l'alternative #47
curl -X POST https://cabine.ai/api/v2/look-tryon \
  -H "Authorization: Bearer VOTRE_CLE" \
  -F user_photo=@client.jpg \
  -F look_id=47

curl -X POST https://cabine.ai/api/v2/look-tryon \
  -H "X-Api-Key: vf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_image_url": "https://maboutique.com/uploads/client.jpg"
  }'

curl -X POST https://cabine.ai/api/v2/look-tryon \
  -H "X-Api-Key: vf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_image_b64": "data:image/jpeg;base64,/9j/4AAQ...",
    "category_id":    14,
    "collection_id":  "gid://shopify/Collection/289346731"
  }'

curl -X POST https://cabine.ai/api/v2/look-tryon \
  -H "X-Api-Key: vf_live_xxx" \
  -F "user_photo=@/chemin/client.jpg" \
  -F "category_id=14"

{
  "success": true,
  "selected_look": {
    "id":          42,
    "name":        "Urban Minimal Denim",
    "description": "Look casual minimal avec veste denim et pantalon beige.",
    "reason":      "Ce look fonctionne particulièrement bien avec votre carnation, les couleurs s'accordent à votre palette — un équilibre subtil pensé pour vous mettre en valeur.",
    "match_score": 0.78,
    "image_url":   "https://cdn.marque.com/looks/look-042.jpg",
    "tags": {
      "style":    ["casual", "minimal", "urban"],
      "occasion": ["daily", "weekend"],
      "season":   ["spring", "summer"],
      "colors":   ["navy blue", "beige", "white"]
    },
    "products": [
      {
        "name":        "Veste denim oversize",
        "product_url": "https://maboutique.com/p/veste-denim-oversize",
        "product_id":  "shopify_gid_xxx"
      },
      {
        "name":        "Pantalon droit beige",
        "product_url": "https://maboutique.com/p/pantalon-droit-beige",
        "product_id":  "shopify_gid_yyy"
      }
    ]
  },
  "alternatives": [
    {
      "id":          47,
      "name":        "Soft Cream Layering",
      "description": "Layering doux crème et beige.",
      "match_score": 0.71,
      "image_url":   "https://cdn.marque.com/looks/look-047.jpg",
      "tags":        { /* idem */ },
      "products":    [ /* idem */ ]
    },
    {
      "id":          53,
      "name":        "Workwear Heritage",
      "description": "Workwear chino et chambray.",
      "match_score": 0.68,
      "image_url":   "https://cdn.marque.com/looks/look-053.jpg",
      "tags":        { /* idem */ },
      "products":    [ /* idem */ ]
    }
  ],
  "tryon": {
    "status":    "completed",
    "image_url": "https://cabine.ai/api/v1/result/a3f8...b2"
  },
  "generation_id":      2087,
  "credits_used":       1,
  "credits_remaining":  161,
  "processing_time_ms": 12340
}

{
  "success": true,
  "selected_look": { /* … identique … */ },
  "alternatives":  [ /* … identique … */ ],
  "tryon": {
    "status":   "pending",
    "poll_url": "https://cabine.ai/api/v1/generation/2087/status"
  },
  "generation_id": 2087,
  "message":       "Génération en cours. Interrogez poll_url pour récupérer le résultat."
}

Créer des Looks V2

La création et la gestion des Looks se fait depuis le back-office Cabine.ai (pas via l'API). Chaque Look est :

• Une tenue complète validée par la marque (image d'un mannequin / photo éditoriale / flatlay)
• Rattaché à une catégorie Cabine.ai et optionnellement à une collection (ID libre côté CMS)
• Décrit par un breakdown forensique de chaque pièce (couleur, matière, finition, hardware, branding…) généré automatiquement par Gemini à l'upload
• Doté d'un prompt try-on dédié (structure rigoureuse mirror-style, verrouillage de l'identité utilisateur, fidélité 1:1 du produit) éditable par la marque
• Doté de tags stylistiques (style, occasion, saison, couleurs) et de compatibilités cibles (carnation, cheveux, morphologie) pour le matcher
• Associé à une liste de produits cliquables (nom + URL fiche produit + ID CMS)

Cycle de vie d'un Look

Workflow recommandé en BO

1. Aller dans Mon compte → Looks → « Nouveau Look »
2. Upload de l'image du Look (JPEG · PNG · WebP, max 15 Mo)
3. Cliquer « Analyser avec Gemini » : le formulaire se pré-remplit (nom, description, tags, targeting, pièces détectées, prompt try-on)
4. Renseigner les URLs des fiches produit pour chaque pièce (point de conversion essentiel)
5. Ajuster les tags/targeting/prompt si besoin
6. « Publier » → le Look devient matchable par POST /api/v2/look-tryon

Bonnes pratiques pour la qualité du matching

• Image du Look : mannequin de face, plein corps visible, fond uni ou éditorial clair, résolution ≥ 800 × 1066 px (ratio portrait 3:4 recommandé)
• Tags stylistiques : remplissez systématiquement style, occasion, saison et couleurs — Gemini fait un bon premier jet, mais une revue humaine améliore significativement le matching
• Targeting morphologique : laissez vide si le Look est universel ; ne remplissez que si une compatibilité est vraiment dominante (ex : robe ajustée → hourglass, rectangle)
• URLs produit : renseignez-les toutes, même pour les accessoires — c'est ce qui transforme l'essayage en revenu
• Catalogue minimum : visez 20+ Looks publiés couvrant 3-4 catégories pour que le matcher ait de la matière. En dessous, les résultats peuvent paraître répétitifs.

Codes d'erreur spécifiques V2 V2

L'endpoint POST /api/v2/look-tryon ajoute plusieurs codes spécifiques à son pipeline. Ils sont retournés avec leur code HTTP approprié et un message lisible en français.

Exemple de réponse d'erreur — quota insuffisant

{
  "success":   false,
  "error":     "quota_exceeded",
  "message":   "Crédits insuffisants pour générer l'essayage.",
  "needed":    2,
  "remaining": 1
}

Intégration PrestaShop

Le module cabineai supporte nativement l'API cabine.ai en mode SaaS. Configurez votre clé API depuis Mon compte → Clés API.

Configuration du module

# BO PrestaShop → Modules → cabineai → Configurer
Mode          : SaaS (API externe)
API Endpoint  : https://cabine.ai/api/v1/generate
API Key       : vf_live_xxxxxxxx...   ← Depuis Mon compte → Clés API
Type de rendu : mirror | universe     ← Optionnel, active le prompt par catégorie

Flux complet recommandé

1. Client clique "Essayer ce vêtement" sur la fiche produit
2. Upload photo → module encode en base64
   POST /api/v1/generate avec :
     - product_id, cart_id, customer_id     (tracking)
     - category, product_name, prompt_type  (prompts intelligents)
3. API résout la catégorie → sélectionne le prompt adapté
4. API génère l'image (~15-90s selon le modèle)
5. API retourne result_url + generation_id → module affiche l'image
6. Client passe commande
7. Webhook PrestaShop → POST /api/v1/conversion avec order_id, product_id, cart_id
8. L'API relie automatiquement la commande à l'essayage d'origine

Appel génération — exemple PHP complet

// Dans le controller AJAX du module (controllers/front/ajax.php)
$product      = new Product((int) Tools::getValue('id_product'));
$category     = new Category($product->id_category_default, Context::getContext()->language->id);

$payload = json_encode([
    'product_image_b64' => 'data:image/jpeg;base64,' . base64_encode(file_get_contents($productImagePath)),
    'user_photo_b64'    => 'data:image/jpeg;base64,' . base64_encode(file_get_contents($userPhotoTmpPath)),
    // Prompts intelligents (optionnels — ignorés si aucun match)
    'category'          => $category->name,
    'product_name'      => $product->name[Context::getContext()->language->id],
    'prompt_type'       => Configuration::get('CABINEAI_PROMPT_TYPE', 'mirror'),
    // Tracking (recommandé)
    'product_id'        => (int) Tools::getValue('id_product'),
    'cart_id'           => (int) Context::getContext()->cart->id,
    'customer_id'       => (int) Context::getContext()->customer->id, // 0 si visiteur
]);

$response = file_get_contents('https://cabine.ai/api/v1/generate', false,
    stream_context_create(['http' => [
        'method'  => 'POST',
        'header'  => "X-Api-Key: vf_live_xxx\r\nContent-Type: application/json",
        'content' => $payload,
        'timeout' => 120,
        'ignore_errors' => true,
    ]])
);

$data = json_decode($response, true);
if ($data['success']) {
    $resultUrl    = $data['result_url'];
    $generationId = $data['generation_id'];
}

Modèle de crédits

Les crédits sont renouvelés le 1er de chaque mois. Les crédits non utilisés ne sont pas reportés. Les crédits bonus (ajoutés manuellement par le support) s'ajoutent aux crédits du plan et sont inclus dans credits_remaining. Aucun crédit n'est débité en cas d'échec du pipeline (transactionnel).

Bonnes pratiques

Génération V1 — Essayage produit unique

• Images produit : fond blanc ou uni, vêtement visible en entier, résolution ≥ 800 px
• Photos utilisateur : portrait face caméra, haut du corps visible, bonne luminosité, résolution ≥ 400 × 400 px
• Timeout client : prévoyez 120 s — la génération peut prendre jusqu'à 90 s selon la charge
• Prompts intelligents : envoyez toujours category + product_name + prompt_type pour bénéficier des prompts optimisés par catégorie
• Tracking : passez toujours product_id et cart_id pour activer le lien automatique avec les conversions

Look Try-On V2 — Personal shopper

• Photo utilisateur : plein corps si possible (le matcher exploite la morphologie), face caméra, bonne luminosité, ≥ 600 × 800 px
• Timeout client : prévoyez 180 s — le pipeline complet (analyse + matching + génération) est plus long que V1
• Catalogue Looks : visez 20+ Looks publiés pour un matching pertinent ; couvrez plusieurs catégories pour ne pas avoir de bruit dans les recommandations
• Filtres : n'utilisez category_id/collection_id que si vous avez une intention claire (page collection, contexte saisonnier) — sinon laissez l'IA choisir parmi tous les Looks
• Affichage côté front : exploitez selected_look.reason tel quel pour créer un effet « personal shopper » authentique ; affichez les alternatives sous l'image principale pour augmenter le panier moyen
• Conversion : les selected_look.products[].product_url sont vos boutons « Acheter cette pièce » ; trackez les clics pour mesurer le taux de transformation par Look

Commun aux deux versions

• Conversions : appelez POST /conversion depuis un hook de confirmation de commande, avec un timeout court et ignore_errors: true pour ne pas bloquer la boutique
• Stockage : sauvegardez result_url / tryon.image_url en base de données — les fichiers sont conservés 4 minutes puis supprimés directement (sauf la génération d'un essayage partagée par l'utilisateur)
• Quota : vérifiez GET /quota avant un batch pour anticiper les erreurs 429 ; V1 et V2 consomment 1 crédit par appel
• Retry : en cas d'erreur 500, attendez 5 s avant de réessayer (max 3 tentatives) — aucun crédit n'est débité tant qu'aucune réponse 200 n'a été retournée