API FoodStudio

Intégrez FoodStudio dans votre boutique, ERP, backend ou Cursor :

  • Sushis — pack d’images studio à partir d’une photo
  • Améliorer couleur — même photo, saturation amplifiée (couleurs plus éclatantes)
  • MCP Cursor · Super Monteur — images (nano-banana-pro) + vidéos Atlas · Kling 3.0 4K depuis Cursor

API shops : https://api.foodstudio.app

MCP : https://mcp.foodstudio.app/super

Créez une clé fsak_… dans Mon compte → API ou un token dédié dans Mon compte → MCP.

Authentification

Toutes les routes /v1/* exigent une clé API :

Authorization: Bearer fsak_votre_cle
# ou
X-Api-Key: fsak_votre_cle

CORS est ouvert sur /v1/* pour les apps front (shops). Préférez l’appel côté serveur pour ne pas exposer la clé.

La même clé fonctionne pour le MCP Cursor (Authorization: Bearer fsak_…).

Générateur Sushis

GET Métadonnées

GET /v1/sushis
curl https://api.foodstudio.app/v1/sushis \
  -H "Authorization: Bearer fsak_…"

# → presets disponibles + solde crédits

POST Générer

POST /v1/sushis

Envoyez l’image source d’une des façons suivantes :

  • image_url — URL HTTPS publique de la photo
  • image_base64 — base64 (+ mime optionnel)
  • source_data_url — data URL complète data:image/…;base64,…
  • multipart image — fichier binaire

Optionnel : preset_ids (tableau) pour limiter les presets. Sans ce champ : pack complet = default_preset_ids du moment (actuellement 19 images → jusqu’à 19 crédits). Les nouvelles vues ajoutées côté FoodStudio arrivent donc automatiquement ; si vous figez une liste preset_ids, il faut la mettre à jour vous-même.

Optionnel : background (alias background_color, bg) — couleur de fond studio. Formats acceptés :

  • Hex : "#FFFFFF", "#1A1A1A", "FFF"
  • RGB : "rgb(26,26,26)", "26,26,26", ou {"r":26,"g":26,"b":26}
  • Nom / texte : "beige", "black", "warm cream", "matte anthracite"

Par défaut : fond blanc / off-white studio. N’affecte pas nobg (transparent), ni les presets dark mood studio-eye-level / studio-macro-dark (fond noir fixe).

Optionnel : style (alias photo_style) — rendu photo global appliqué à toutes les vues studio (pas nobg). Défaut : standard.

  • standard — rendu studio actuel, équilibré
  • ultra-hd — Ultra Photo Réaliste HD (macro détaillée, softbox, specular, DoF f/2.8, 8K)
  • spectacular — Spectacular Highlights (reflets punchy, high-gloss luxe)
  • soft-luxe — Soft Luxe (lumière douce fine-dining)
  • crisp-catalog — Crisp Catalog (e-commerce, netteté uniforme)
  • warm-premium — Warm Premium Macro (colorimétrie chaude crème, macro détaillée, high-key soft)

Optionnel : model (alias image_model) — moteur IA pour tout le pack. Défaut : gemini.

  • gemini — Google Gemini 2.5 Flash Image (défaut) — prompts studio longs + style
  • xai/grok-imagine-image-quality — xAI Grok Imagine Quality (via AI Gateway)

Pipeline : toutes les vues studio partent de l’image nobg (Suppression du fond). Si nobg n’est pas dans preset_ids mais qu’une vue en a besoin, il est généré automatiquement en premier.

Réponse

{
  "ok": true,
  "urls": [
    "https://api.foodstudio.app/files/outputs/sushis/…png",
    "https://api.foodstudio.app/files/outputs/sushis/…jpg"
  ],
  "images": [
    {
      "preset_id": "nobg",
      "url": "https://api.foodstudio.app/files/…",
      "mime": "image/png",
      "image_id": "i_…"
    }
  ],
  "background": { "label": "#FFFBFA", "hex": "#FFFBFA", "rgb": { "r": 255, "g": 251, "b": 250 }, "raw": "#FFFBFA" },
  "style": { "id": "standard", "title": "Standard" },
  "model": { "id": "gemini", "title": "Gemini Flash Image" },
  "credits_left": 984,
  "credits_used": 19
}

Utilisez urls pour brancher directement votre shop (carousel, fiche produit, etc.).

Presets par défaut (pack complet, 19) : les 17 vues studio classiques + studio-one-item et studio-two-item (voir ci-dessous).

Presets one item / two item

Deux presets dédiés (prompts courts, format 1:1). La couleur background remplace #FFFBFA dans le prompt. Fonctionnent avec gemini ou xai/grok-imagine-image-quality. Le paramètre style n’est pas appliqué sur ces deux presets.

studio-one-item — une pièce centrée :

Make hd version, centered on seamless {background} background, studio lighting, subtle shadow, and reflection. Make 1:1 size square format.

studio-two-item — duo debout + couché, angle 3/4 :

Make hd version, soft diffused studio lighting background, studio lighting, subtle shadow, and reflection. Make two item, on a pure {background} reflective surface, one standing vertically, the other lying horizontally beside it, shot from a 3/4 angle, clean {background} background, subtle reflection. Avoid too perfect texture, give photorealistic shot. Make 1:1 size square format.

Couleur {background} : valeur de background si fournie, sinon #FFFBFA.

curl https://api.foodstudio.app/v1/sushis \
  -H "Authorization: Bearer fsak_…" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://cdn.monshop.com/produits/sushi.jpg",
    "model": "xai/grok-imagine-image-quality",
    "background": "#FFFBFA",
    "preset_ids": ["nobg", "studio-one-item", "studio-two-item"]
  }'

Progression (SSE) — progress bar

Sans stream, la réponse JSON arrive à la fin du pack. Pour afficher une barre de progression style par style, activez le stream :

  • Body JSON : "stream": true
  • Query : ?stream=1
  • Header : Accept: text/event-stream

Réponse text/event-stream avec un événement par étape :

event: start
data: {"type":"start","total":12,"presets":[{"id":"nobg","title":"…"},…]}

event: preset_start
data: {"type":"preset_start","index":1,"total":12,"preset_id":"nobg","title":"…","ratio":0}

event: preset_done
data: {"type":"preset_done","index":1,"total":12,"preset_id":"nobg","url":"https://…","ratio":0.083,…}

event: preset_error
data: {"type":"preset_error","preset_id":"studio-side","error":"…","ratio":0.16,…}

event: done
data: {"type":"done","ok":true,"urls":[…],"images":[…],"credits_left":970,"credits_used":11}

event: error
data: {"ok":false,"error":"insufficient_credits",…}

Utilisez ratio (0→1) ou index/total pour la progress bar. Chaque preset_done contient déjà l’URL de l’image (affichage progressif possible).

Améliorer couleur

Envoie une photo → reçoit la même image avec la saturation amplifiée (couleurs plus éclatantes), sans changer le cadrage ni le sujet.

1 crédit par appel. Intensité au choix :

  • Presets : soft (25), medium (50, défaut), hard (80)
  • Ou niveau précis : entier de 1 à 99 (sur 100)

GET Métadonnées

GET /v1/enhance-color
curl https://api.foodstudio.app/v1/enhance-color \
  -H "Authorization: Bearer fsak_…"

POST Amplify saturation

POST /v1/enhance-color
curl https://api.foodstudio.app/v1/enhance-color \
  -H "Authorization: Bearer fsak_…" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://cdn.monshop.com/produits/plat.jpg",
    "intensity": "medium"
  }'

# intensity peut aussi être "soft", "hard", ou un nombre 1–99 :
# "intensity": 65

Réponse

{
  "ok": true,
  "url": "https://api.foodstudio.app/files/outputs/enhance-color/….jpg",
  "urls": ["https://api.foodstudio.app/files/outputs/enhance-color/….jpg"],
  "image_id": "i_…",
  "mime": "image/jpeg",
  "intensity": { "preset": "medium", "level": 50 },
  "credits_left": 990,
  "credits_used": 1
}

url (et urls[0]) pointe vers l’image saturée. Multipart supporté : -F image=@photo.jpg -F intensity=hard.

Générer dans une sélection

Utilisé par l’éditeur (Filtres › IA › Générer… / ⌘G).

  • Crop — source_data_url + prompt → régénère toute la zone.
  • Outpaint — context_data_url + mask_data_url (blanc = marges vides) + guide_data_url optionnel → invente seulement les zones vides, sans étirer le sujet. L’éditeur colle le résultat uniquement dans le masque vide.

1 crédit par appel. Réponse inclut mode : crop | context.

GET Métadonnées

GET /v1/generate-selection
curl https://api.foodstudio.app/v1/generate-selection \
  -H "Authorization: Bearer fsak_…"

POST Générer (crop)

POST /v1/generate-selection
curl https://api.foodstudio.app/v1/generate-selection \
  -H "Authorization: Bearer fsak_…" \
  -H "Content-Type: application/json" \
  -d '{
    "source_data_url": "data:image/png;base64,…",
    "prompt": "un bol de ramen fumant, lumière naturelle"
  }'

POST Outpaint (marges vides)

curl https://api.foodstudio.app/v1/generate-selection \
  -H "Authorization: Bearer fsak_…" \
  -H "Content-Type: application/json" \
  -d '{
    "context_data_url": "data:image/png;base64,…",
    "mask_data_url": "data:image/png;base64,…",
    "guide_data_url": "data:image/png;base64,…",
    "prompt": "prolonge le décor autour du sujet"
  }'

Réponse

{
  "ok": true,
  "url": "https://api.foodstudio.app/files/outputs/generate-selection/….png",
  "urls": ["https://api.foodstudio.app/files/outputs/generate-selection/….png"],
  "image_id": "i_…",
  "mime": "image/png",
  "mode": "context",
  "prompt": "prolonge le décor autour du sujet",
  "credits_left": 989,
  "credits_used": 1
}

MCP Cursor · Super Monteur

Serveur MCP distant pour générer des images et des vidéos FoodStudio depuis Cursor (ou tout client MCP compatible Streamable HTTP).

Endpoint

https://mcp.foodstudio.app/super

Page d’accueil / health : mcp.foodstudio.app/super · GET /health

Authentification

Même clé API fsak_… que l’API shops. Créez un token dédié dans Mon compte → MCP (recommandé) ou réutilisez une clé API.

Authorization: Bearer fsak_votre_cle

Config Cursor

{
  "mcpServers": {
    "foodstudio-super": {
      "url": "https://mcp.foodstudio.app/super",
      "headers": {
        "Authorization": "Bearer fsak_VOTRE_TOKEN"
      }
    }
  }
}

Défauts

  • Image — google/nano-banana-pro
  • Vidéo — Atlas Cloud → kwaivgi/kling-v3.0-4k/image-to-video

Raccourci site

Pour animer une image produit depuis Cursor, appelez l’outil image_to_video avec image_url ou image_data_url (+ motion_prompt optionnel). Le MCP crée le projet, importe l’image, lance Kling 4K et renvoie video_url.

Outils MCP

Appelez aussi l’outil capabilities dans Cursor pour la doc live.

Compte & projets

  • capabilities — documentation complète du MCP
  • whoami — utilisateur + défauts modèles
  • list_projects / create_project / get_project
  • list_jobs / cancel_job

Images & planches

  • create_moodboard — planche objet (défaut nano-banana-pro) ; option multi_angle
  • list_moodboards — planches de l’utilisateur

Super Monteur

Arbre de calques images → vidéos image-to-video. Flux typique :

  1. create_project (builder)
  2. super_import_image ou super_generate_image (racine)
  3. Optionnel sur un parent :
    • edit_mode=add — ➕ Ajouter un élément (garde la photo, ajoute seulement ce que vous décrivez)
    • edit_mode=transform — 🎬 Transformer la vue (nouvel angle / cadrage / distance)
    • edit_mode=replace — 🔄 Remplacer uniquement la zone de l’objet (inpainting soft — préférer à add si un faux objet est déjà dans l’image)
    • edit_mode=compose — 🧩 Fond + objet (cutout/moodboard) + compose.position / compose.scale
  4. Refs stables (sans dilution) : object_planche_id (1 moodboard objet) + place_planche_ids / place_ref_ids (1–2 photos lieu)
  5. super_generate_video (Atlas · Kling 3.0 4K)
  6. super_wait ou wait: true sur les tools
  • super_list — nodes + vidéos (statuts, URLs)
  • super_import_image — importe une image existante comme node prêt (image_url ou image_data_url)
  • super_generate_image — génère 1–3 images (add / transform / replace / compose, modèle défaut nano-banana-pro)
  • super_generate_video — anime un node (défaut Kling 4K ; option end_node_id pour transition A→B)
  • super_wait — poll jusqu’à done / error
  • super_delete_node — supprime un node et ses descendants
  • image_to_video — raccourci complet image → vidéo 4K

Exemple — replace + refs typées

// Remplacer uniquement la zone d’un objet déjà présent (faux rendu) :
{
  "project_id": "vp_…",
  "parent_id": "vsn_…",
  "edit_mode": "replace",
  "prompt": "the white cabin cruiser in the center of the bay",
  "object_planche_id": "vtm_…",
  "place_planche_ids": ["vtm_place_…"]
}

// Compose dédié fond + cutout :
{
  "project_id": "vp_…",
  "parent_id": "vsn_…",
  "edit_mode": "compose",
  "prompt": "boat gently resting on calm turquoise water near the shore",
  "object_planche_id": "vtm_…",
  "compose": { "position": "foreground", "scale": "large" }
}

Exemple — image → vidéo

// Dans Cursor, via l’outil MCP image_to_video :
{
  "image_url": "https://cdn.monsite.com/hero-plat.jpg",
  "motion_prompt": "Slow cinematic push-in, subtle steam, natural light",
  "duration_sec": 5
}

// → { project_id, node_id, video_id, status, video_url }

API Video sous-jacente

Le MCP wrappe https://video-api.foodstudio.app (même auth fsak_). Exemples de routes utilisées :

  • POST /projects — créer un projet builder
  • GET /projects/:id/super — état Super Monteur
  • POST /projects/:id/super/import — importer une image
  • POST /projects/:id/super/nodes — générer image(s) (edit_mode)
  • POST /projects/:id/super/nodes/:nodeId/video — générer vidéo
  • POST /tools/moodboard — planche objet

UI complète : video.foodstudio.app

Exemples pour un shop externe

Node — Sushis (Gemini)

const res = await fetch('https://api.foodstudio.app/v1/sushis', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.FOODSTUDIO_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    image_url: 'https://cdn.monshop.com/produits/sushi-saumon.jpg',
    // preset_ids: ['nobg', 'studio-side', 'studio-top'], // optionnel
    // background: '#1A1A1A',
    // style: 'warm-premium',
    model: 'gemini', // défaut
  }),
});
const data = await res.json();
if (!data.ok) throw new Error(data.error);
console.log(data.urls);

Node — Sushis (one / two item + Grok)

const res = await fetch('https://api.foodstudio.app/v1/sushis', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.FOODSTUDIO_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    image_url: 'https://cdn.monshop.com/produits/sushi-saumon.jpg',
    model: 'xai/grok-imagine-image-quality',
    background: '#FFFBFA', // défaut si omis
    preset_ids: ['nobg', 'studio-one-item', 'studio-two-item'],
  }),
});
const data = await res.json();
if (!data.ok) throw new Error(data.error);
console.log(data.model, data.background, data.urls);

Node — Sushis avec progress bar (SSE)

const res = await fetch('https://api.foodstudio.app/v1/sushis', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.FOODSTUDIO_API_KEY,
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream',
  },
  body: JSON.stringify({
    image_url: 'https://cdn.monshop.com/produits/sushi-saumon.jpg',
    stream: true,
  }),
});
const reader = res.body.getReader();
const dec = new TextDecoder();
let buf = '';
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += dec.decode(value, { stream: true });
  const chunks = buf.split('\n\n');
  buf = chunks.pop() || '';
  for (const chunk of chunks) {
    const ev = (chunk.match(/^event: (.+)$/m) || [])[1];
    const raw = (chunk.match(/^data: (.+)$/m) || [])[1];
    if (!ev || !raw) continue;
    const data = JSON.parse(raw);
    if (ev === 'preset_start' || ev === 'preset_done') {
      setProgress(Math.round((data.ratio || 0) * 100)); // votre UI
      setLabel(data.title); // ex. "Plongée légère 45°"
    }
    if (ev === 'preset_done') appendImage(data.url); // affichage progressif
    if (ev === 'done') console.log('pack OK', data.urls);
    if (ev === 'error') throw new Error(data.error);
  }
}

Node — Améliorer couleur

const res = await fetch('https://api.foodstudio.app/v1/enhance-color', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.FOODSTUDIO_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    image_url: productImageUrl,
    intensity: 'hard', // ou 1–99
  }),
});
const data = await res.json();
// data.url → photo aux couleurs plus éclatantes
console.log(data.url);

PHP

$ch = curl_init('https://api.foodstudio.app/v1/sushis');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('FOODSTUDIO_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'image_url' => $productImageUrl,
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
$urls = $data['urls'] ?? [];

Upload multipart

curl https://api.foodstudio.app/v1/sushis \
  -H "Authorization: Bearer fsak_…" \
  -F "image=@/path/sushi.jpg"

Erreurs courantes

  • 401 api_key_required / auth_required — clé manquante ou invalide (API ou MCP)
  • 400 missing_image — aucun image_url / fichier
  • 402 insufficient_credits — rechargez sur my.foodstudio.app
  • 413 image_too_large — image source trop lourde (~10 Mo max)
  • 502 no_images_generated / enhance_failed — échec IA (réessayer)
  • 400 invalid_intensity — utilisez soft / medium / hard ou 1–99
  • 408 timeout (MCP) — génération vidéo trop longue ; relancer super_wait / super_list

Crédits & facturation

1 crédit = 1 image générée (API shops). Le pack Sushis par défaut produit jusqu’à 8 images. enhance-color = 1 crédit.

Les générations vidéo / Super Monteur via MCP utilisent votre compte FoodStudio Video (crédits / coûts selon le moteur).

Achetez des crédits sur Mon compte. Gérez vos clés dans API et vos tokens Cursor dans MCP.