API Reference

Documentation API

API REST pour intégrer la cabine d'essayage virtuel IA dans vos boutiques e-commerce.

Base URL : https://cabine.ai/api/v1 · Format : application/json

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.

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

X-Api-Key: vf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Via Authorization Bearer

Authorization: Bearer vf_live_xxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Ne commitez jamais votre clé API dans votre code source. Stockez-la dans une variable d'environnement ou dans la configuration de votre module.

Gestion des erreurs

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

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

HTTP	Code erreur	Description
401	authentication_error	Clé API manquante, invalide ou révoquée
402	no_active_subscription	Aucun abonnement actif sur ce compte
403	model_not_allowed	Modèle non inclus dans votre plan
422	invalid_param	Paramètre manquant ou URL invalide
429	quota_exceeded	Quota de crédits mensuel épuisé
500	generation_failed	Erreur API Gemini ou génération impossible

Génération d'essayage

POST /api/v1/generate Lance une génération IA

Envoie deux images (URL) + un prompt optionnel. Retourne l'URL de téléchargement de l'image générée.

Sources d'images — 3 modes (mixables)

Les champs product_image_* et user_photo_* acceptent chacun 3 formats. Utilisez celui qui correspond à votre architecture.

Paramètre	Type		Description
IMAGE PRODUIT — choisir l'un des 3
product_image_url	string	URL	URL HTTPS publique de l'image produit
product_image_b64	string	base64	Image encodée en base64 (avec ou sans préfixe `data:image/...;base64,`)
product_image	file	multipart	Fichier image en `multipart/form-data`
PHOTO UTILISATEUR — choisir l'un des 3
user_photo_url	string	URL	URL HTTPS publique de la photo de la personne
user_photo_b64	string	base64	Photo encodée en base64
user_photo	file	multipart	Fichier photo en `multipart/form-data`
OPTIONS
prompt	string	optionnel	Instructions personnalisées. Si absent, le prompt haute-fidélité par défaut est utilisé.
model	string	optionnel	Modèle IA. Défaut : `gemini-3.1-flash-image-preview`
customer_id	int	optionnel	ID client côté CMS (PrestaShop, etc.) — pour filtrage et exports
cart_id	int	optionnel	ID panier côté CMS — pour tracking conversion

Mode 1 — URL publique (JSON)

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",
    "customer_id":        12345,
    "cart_id":            67890
  }'

Mode 2 — Base64 (dev local, images non publiques) ✅ recommandé PrestaShop

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...",
    "customer_id":        12345,
    "cart_id":            67890
  }'

Mode 3 — Multipart/form-data (upload direct)

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 "customer_id=12345" \
  -F "cart_id=67890"

Réponse succès (200)

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

result_url est accessible sans authentification via un token sécurisé (64 caractères hex). Sauvegardez-la dans votre base de données — elle pointe vers le fichier stocké sur nos serveurs selon la durée de votre plan :
Starter : 7 jours · Growth : 30 jours · Scale : 90 jours.
Après expiration, la route retourne HTTP 410 Gone.

Champs de la réponse

Champ	Type	Description
success	bool	`true` si la génération a réussi
result_url	string	URL de téléchargement de l'image générée (token 64 hex, accessible sans auth)
generation_id	int	ID interne de la génération — référencez-le pour vos logs
credits_used	int	Crédits consommés par cette génération (dépend du modèle choisi)
credits_remaining	int	Crédits restants sur votre abonnement ce mois-ci
processing_time_ms	int	Durée de traitement en millisecondes

Intégration recommandée PrestaShop — base64 (fonctionne en local et en prod)

// Encoder les deux images en base64 côté PrestaShop
$productB64 = 'data:image/jpeg;base64,' . base64_encode(file_get_contents($productImagePath));
$userB64    = 'data:image/jpeg;base64,' . base64_encode(file_get_contents($uploadedPhotoTmpPath));

$body = json_encode([
    'product_image_b64' => $productB64,
    'user_photo_b64'    => $userB64,
    'customer_id'       => (int) Context::getContext()->customer->id,
    'cart_id'           => (int) Context::getContext()->cart->id,
]);

$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' => $body,
        'timeout' => 120,
    ]])
);

$data = json_decode($response, true);
if ($data['success']) {
    $resultUrl = $data['result_url']; // URL téléchargeable 30j
}

Le mode base64 fonctionne partout — dev local, staging, prod — sans que le serveur cabine.ai ait besoin d'accéder à votre domaine PrestaShop.

Consulter son quota

GET /api/v1/quota Solde de crédits

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

{
  "success":            true,
  "plan":               "Pro",
  "plan_slug":          "pro",
  "credits_total":      200,
  "credits_used":       37,
  "credits_remaining":  163,
  "usage_percent":      18,
  "renews_at":          "2025-02-01"
}

Modèles disponibles

GET /api/v1/models Liste des modèles selon votre plan

{
  "success": true,
  "models": [
    { "id": "gemini-3.1-flash-image-preview", "label": "Flash Preview — défaut ✅",  "credits_per_generation": 1, "available": true },
    { "id": "gemini-2.5-flash-image",          "label": "Flash Image (rapide)",       "credits_per_generation": 1, "available": true },
    { "id": "gemini-3-pro-image-preview",      "label": "Pro Image Preview (max)",    "credits_per_generation": 1, "available": false }
  ]
}

Intégration PrestaShop

Le module mtg_cabine.aiting 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 → mtg_cabine.aiting → Configurer
Mode          : SaaS (API externe)
API Endpoint  : https://cabine.ai/api/v1/generate
API Key       : vf_live_xxxxxxxx...   ← Depuis Mon compte → Clés API

Flux complet dans le module

1. Client clique "Essayer ce vêtement" sur la fiche produit
2. Upload photo → module encode en base64 + envoie POST /api/v1/generate
   avec customer_id et cart_id pré-remplis automatiquement
3. API génère l'image (~15-60s selon le modèle)
4. API retourne result_url → module affiche l'image côte-à-côte
5. Client peut télécharger, ajouter au panier ou relancer un essai

Envoi complet recommandé depuis PrestaShop

// Dans le controller AJAX du module (controllers/front/ajax.php)
$payload = [
    '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)),
    'customer_id'       => (int) Context::getContext()->customer->id,   // 0 si visiteur
    'cart_id'           => (int) Context::getContext()->cart->id,
    'model'             => 'gemini-2.5-flash-image',                    // selon votre plan
];

Pourquoi base64 et non URL ? Votre boutique PrestaShop peut être en local, staging ou derrière un VPN — le serveur cabine.ai ne pourrait pas accéder à une URL interne. Le base64 encode l'image directement dans la requête et fonctionne partout.

Modèle de crédits

1 essayage = 1 crédit, quel que soit le modèle utilisé. Le modèle par défaut est le plus récent disponible.
Vous pouvez spécifier un autre modèle via le champ model, sans surcoût.

Modèle	Crédit	Qualité	Temps estimé
gemini-3.1-flash-image-preview	1	Supérieure	~30-60s	Défaut
gemini-2.5-flash-image	1	Excellente	~15-30s
gemini-3-pro-image-preview	1	Premium	~60-120s	Scale uniquement

Les essayages sont renouvelés le 1er de chaque mois. Les essayages non utilisés ne sont pas reportés.

Bonnes pratiques

Images produit : fond blanc ou uni, vêtement visible en entier, résolution ≥ 800px
Photos utilisateur : portrait face caméra, haut du corps visible, bonne luminosité, résolution ≥ 400x400px
Timeout : prévoir un timeout de 120s côté client (la génération peut prendre jusqu'à 90s)
Stockage : sauvegardez result_url dans votre BDD — les fichiers sont conservés 30 jours
Quota : vérifiez /quota avant chaque batch pour éviter les erreurs 429
Retry : en cas d'erreur 500, attendez 5s avant de réessayer (max 3 tentatives)

Des questions ? support@cabine.ai

Créer un compte gratuit →