Passer au contenu principal
Le server expose dix-huit outils. Neuf sont gratuits — les cinq lectures (list_models, get_model, list_image_engines, get_job_status, get_credit_balance), les deux outils de gestion de modèles (create_model, update_model) et les deux outils d’upload (prepare_image_upload, complete_image_upload). Les neuf autres coûtent des credits du pool de ton organisation, aux mêmes tarifs que l’app et l’API REST.
Bientôt disponible : improve_prompt, un dix-neuvième outil qui coûte 1 credit par appel. Il n’est pas encore dans la liste des outils du server ; il y apparaît dès que l’amélioration de prompts est activée. Sa ligne et sa section ci-dessous le décrivent tel qu’il sera au lancement.
Un appel d’outil rejeté pour un scope manquant renvoie une erreur d’outil structurée (pas un crash) nommant le scope dont il a besoin. Les clés sont créées avec tous les scopes par défaut ; un admin peut restreindre ou élargir une clé dans Settings → API Keys.

Paramètres

  • category (optionnel) — filtre sur l’un de style, object, person, setting.
Renvoie les modèles prêts de ton organisation avec id, name, category et une thumbnail_url presignée. Utilise les ids ou les noms comme style_id / object_ids / person_ids / setting_ids dans generate_image et generate_video — un nom est résolu vers un modèle visible pour toi. Les moteurs text-to-image généraux ne sont pas des modèles entraînés — list_image_engines les liste.
  • model_id (requis) — l’id du modèle.
Renvoie le détail complet : statut, disponibilité, URLs presignées des images de référence, le prompt par défaut et les mots déclencheurs.
  • name (requis) — le nom du modèle.
  • category (requis) — l’un de style, object, person, setting.
  • images (requis) — 1–10 images de référence. Chacune est soit une URL https publique (≤ 10 Mo chacune) soit un data URI base64 inline (data:image/png;base64,…) — image/jpeg, image/png ou image/webp. La requête MCP entière est limitée à 1 Mo, donc les images base64 inline ne peuvent porter qu’environ 750 Ko de données de fichier au total — envoie les images plus grandes sous forme d’URLs https.
  • instruction (optionnel) — la guidance toujours appliquée du modèle (≤ 8000 caractères), injectée comme directive obligatoire (“MUST FOLLOW”) dans chaque génération qui compose le modèle. Voir Entraînement de modèles.
  • webhook_url (optionnel) — une URL https notifiée une fois lorsque l’entraînement atteint un statut terminal.
Async — renvoie { id, status: "pending", estimated_credits } immédiatement ; interroge get_job_status(kind="model", id=…) (qui nécessite aussi le scope models.read) jusqu’à completed ou failed, puis utilise l’id du modèle dans generate_image / generate_video. Gratuit — la création de modèle ne déduit aucun credit. Les uploads presignés de gros fichiers de modèle sont réservés au REST (non exposés via MCP) — utilise POST /models/prepare pour cela. Un image_id issu de prepare_image_upload n’est pas accepté ici.
  • model_id (requis) — le modèle à mettre à jour.
  • name (optionnel) — un nouveau nom de modèle.
  • default_prompt (optionnel) — un nouveau prompt par défaut.
  • instruction (optionnel) — la guidance toujours appliquée du modèle (≤ 8000 caractères). Envoie une chaîne vide pour l’effacer.
Fournis au moins un de name, default_prompt ou instruction ; les champs omis restent inchangés. Synchrone — renvoie immédiatement le modèle mis à jour complet (même forme que get_model). Gratuit.
Aucun paramètre. Renvoie { data: [...], unavailable_reason } — une entrée par moteur text-to-image que tu peux utiliser, le moteur par défaut en premier : id, name, is_default, provider_family, aspect_ratios, default_aspect_ratio, resolutions, default_resolution, max_num_outputs, credits_per_image (par résolution ; une requête coûte cette valeur × num_outputs), supports_trained_refs et supports_color_palette. Le contenu est le même que GET /images/models. Passe l’id d’une entrée comme engine à generate_image.Si ton organisation génère uniquement avec ses modèles entraînés, data est vide et unavailable_reason vaut organization_restricted ; sinon il vaut null. Gratuit. Scope images.generate.
Bientôt disponible — absent de la liste des outils du server tant que l’amélioration de prompts n’est pas activée.
  • prompt (requis) — le prompt à améliorer : 3 à 5000 caractères après suppression des espaces de début et de fin, avec les mêmes règles que pour tout prompt Samsa (pas de < ni de >, pas de barres obliques inverses, pas de sauts de ligne ni de tabulations).
  • target (requis) — image ou video : le média auquel le prompt amélioré est destiné.
  • language (optionnel) — un tag de langue BCP-47 comme en ou de pour la langue du prompt amélioré. Omis : le prompt amélioré garde la langue de ton prompt.
  • idempotency_key (optionnel) — 1 à 255 caractères ASCII imprimables. La même clé avec les mêmes arguments dans les 24 heures renvoie le résultat enregistré et n’est jamais facturée deux fois ; la même clé avec d’autres arguments est rejetée (idempotency_key_reused), et une clé dont le premier appel est encore en cours renvoie idempotency_in_progress. Une clé dont l’appel a échoué renvoie à nouveau cette erreur : utilise une nouvelle clé pour une nouvelle tentative payante. Les clés sont propres au titulaire des identifiants (le créateur de la clé API ou l’utilisateur OAuth) au sein de l’organisation, et partagent un même espace de noms avec le header REST Idempotency-Key.
Synchrone — renvoie directement { improved_prompt, target, language, credits_charged } ; il n’y a aucun job à interroger. Passe improved_prompt comme prompt à generate_image ou generate_video. Coût : 1 credit par appel, débité avant que le modèle ne tourne ; si le fournisseur d’IA échoue, le credit est remboursé et l’outil renvoie un provider_error. Les erreurs ont la même forme structurée d’erreur d’outil que pour les autres outils. Scope : l’un de images.generate, images.edit ou videos.generate. Équivalent REST : POST /prompts/improve.
  • prompt (requis) — le prompt texte.
  • engine (optionnel) — le modèle text-to-image : nano_banana_pro (par défaut), nano_banana_2_1, nano_banana_2, nano_banana, imagen_4, seedream_4 ou flux_1_pro. Omets-le pour utiliser nano_banana_pro. Les limites de chaque moteur sont dans Moteurs, ou appelle list_image_engines.
  • style_id, object_ids, person_ids, setting_ids (optionnels) — ids ou noms de modèles entraînés issus de list_models à composer (un nom est résolu vers un modèle visible pour toi).
  • color_palette (optionnel) — une palette de couleurs à appliquer, donnée par son nom ou son id (comme les références de modèles entraînés).
  • num_outputs (1–4, par défaut 1), aspect_ratio (par défaut "1:1"), resolution (par défaut "1K").
aspect_ratio et resolution sont validés selon le moteur : nano_banana_pro, nano_banana_2_1 et nano_banana_2 acceptent 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9, 4:1, 1:4, 8:1, 1:8 en 1K / 2K / 4K ; nano_banana les dix premiers en 1K ; imagen_4 1:1, 16:9, 9:16, 4:3, 3:4 en 1K / 2K ; seedream_4 et flux_1_pro 1:1, 16:9, 9:16, 4:3, 3:4, 21:9 en 1K. Un moteur inconnu ou une valeur non prise en charge renvoie un 422 qui nomme les valeurs valides.Les modèles entraînés et color_palette fonctionnent uniquement avec nano_banana_pro, nano_banana_2_1 et nano_banana_2 ; sur tout autre moteur ils renvoient 422 — ils ne sont jamais ignorés, et le moteur n’est jamais changé. Certaines organisations génèrent uniquement avec leurs modèles entraînés : là, tout engine renvoie 422 — omets engine et passe au moins un modèle entraîné ou une color_palette.Async — renvoie { id, status: "pending", estimated_credits } immédiatement. Coût : 5 × num_outputs × resolution (1K ×1, 2K ×2, 4K ×4), déduit à la soumission — identique sur chaque moteur.
  • prompt (requis) — comment éditer l’image.
  • Exactement un de image_id (une image de ton contexte Samsa, par exemple issue de complete_image_upload) ou image_url (une URL https publique). Le ratio de l’image source est conservé.
  • engine (optionnel) — nano_banana_pro (Nano Banana Pro, par défaut), nano_banana_2 (Nano Banana 2), nano_banana_2_1 (Nano Banana 2.1), gemini (Nano Banana via FAL) ou kontext (Flux Kontext). Un moteur inconnu renvoie 422 en nommant les valeurs valides. Voir Engines et credits.
  • resolution (optionnel) — 1K (par défaut), 2K ou 4K sur nano_banana_pro, nano_banana_2 et nano_banana_2_1. gemini et kontext ont une résolution fixe : omets resolution pour eux (une valeur renvoie 422).
  • num_images (optionnel) — 1–4, par défaut 1.
  • style_id, object_ids, person_ids, setting_ids (optionnels) — ids ou noms de modèles entraînés issus de list_models à réutiliser pour des éditions fidèles à ta marque (un nom est résolu vers un modèle visible pour toi), à parité avec generate_image.
  • color_palette (optionnel) — une palette de couleurs à appliquer, donnée par son nom ou son id.
Les modèles entraînés et color_palette ne fonctionnent qu’avec nano_banana_pro (y compris quand tu omets engine). Nommer un autre moteur avec eux renvoie 422 avant tout débit — le moteur n’est jamais changé. Les éditions masquées sont réservées au REST et tournent sur nano_banana_pro ou gemini.Async — renvoie { id, status: "pending", estimated_credits, engine, resolution }. engine et resolution sont les valeurs effectives de l’édition (resolution vaut null sur gemini et kontext). Coût par output : 5 credits × résolution sur les trois moteurs Nano Banana (1K 5, 2K 10, 4K 20), 5 fixes sur gemini et kontext ; × num_images, déduit à la soumission. Par exemple, edit_image(prompt=…, image_id=…, resolution="4K") renvoie estimated_credits: 20.
  • prompt (requis) — comment transformer les sources.
  • images (requis) — 1–14 sources ; chaque élément est soit { image_id } soit { image_url } (une URL https). L’ordre des sources est préservé. Pas de base64 en MCP — voir Entrées d’image.
  • engine (optionnel) — nano_banana_pro (par défaut), nano_banana_2 ou nano_banana_2_1 (Nano Banana 2.1).
  • aspect_ratio (optionnel) — validé contre la liste du moteur (nano_banana_2 et nano_banana_2_1 autorisent en plus 4:1, 1:4, 8:1, 1:8) ; omis, la forme de la source est préservée.
  • resolution (1K par défaut, 2K, 4K), num_outputs (par défaut 1).
Async — interroge get_job_status(kind="img2img", id=…). Coût : 5 × num_outputs × résolution (1K ×1, 2K ×2, 4K ×4). Scope images.edit.
  • Un de image_id ou image_url (requis).
  • target (optionnel) — ce qui peut changer : everything (par défaut), person, object, scene.
  • creativity (optionnel) — subtle ou creative (par défaut).
  • variation_instructions / preservation_instructions (optionnels) — texte libre, ≤ 2000 caractères chacun.
  • num_outputs (1–4, par défaut 1).
La résolution de sortie est héritée de la source (pas d’argument resolution). Async — interroge get_job_status(kind="image_variation", id=…). Coût : 5 × num_outputs × résolution source (1K ×1, 2K ×2, 4K ×4 ; une source sans dimensions récupérables est facturée à 1K). Scope images.transform.
  • aspect_ratio (requis) — un de 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16.
  • Un de image_id ou image_url (requis).
  • resolution (1K par défaut, 2K, 4K), num_outputs (1–4, par défaut 1).
  • prompt (optionnel) — guidage pour la zone nouvellement exposée.
  • placement (optionnel) — { gravity, scale } positionnant la source sur le canevas (gravity un de center [par défaut], top, bottom, left, right, top_left, top_right, bottom_left, bottom_right ; scale dans (0, 1]).
Redimensionne par outpainting — le server remplit le nouveau canevas d’une extension assortie au style. S’il n’y a rien de nouveau à générer et qu’aucun prompt n’est fourni, il renvoie l’image aplatie et rembourse les outputs inutilisés. Async — interroge get_job_status(kind="image_resize", id=…). Coût : 5 × num_outputs × résolution. Scope images.transform.
  • target_resolution (requis) — 2K, 4K, 6K, 8K, 10K, 12K, 14K, 16K, 20K, 24K, 28K, 32K, 38K (les classes au-dessus de 16K sont réservées à crystal).
  • Un de image_id ou image_url (requis).
  • model (optionnel) — seedvr, crystal (par défaut), magnific-creative, magnific-precision.
  • options (optionnel) — par modèle, strictement validées : options.magnific_creative (prompt, optimized_for, creativity/hdr/resemblance/fractality dans −10..10, engine) ou options.magnific_precision (sharpen/smart_grain/ultra_detail dans 0..100, flavor). seedvr/crystal ne prennent pas d’options.
Les limites de facteur/surface par modèle sont validées avant la facturation. Async — interroge get_job_status(kind="image_upscale", id=…). Coût : le palier de résolution × le multiplicateur du modèle (Magnific ×3) ; crystal au-dessus de 12K est facturé selon les mégapixels de sortie — voir tarification. Scope images.transform.
  • Un de image_id ou image_url (requis).
Produit un PNG transparent ; il n’y a pas de paramètre de modèle. Async — interroge get_job_status(kind="image_background_removal", id=…). Coût : 1 credit sur un miss ; 0 sur un cache hit — un image_id que tu possèdes qui a déjà un résultat de suppression d’arrière-plan renvoie immédiatement { status: "completed", estimated_credits: 0 }. Scope images.transform.
  • svg_acceptance (requis) — doit être le booléen littéral true.
  • Un de image_id ou image_url (requis).
  • engine (optionnel, par défaut recraft) — recraft ou ideogram.
  • mode (optionnel) — default (détaillé, par défaut) ou simple. Valide uniquement avec engine: "ideogram" ; toute autre combinaison est rejetée 422 sans facturation.
Produit un SVG. Un SVG ne peut porter ni manifeste C2PA ni filigrane, donc la sortie vectorielle est livrée sans signature — voir Provenance du contenu. La reconnaissance est une preuve de divulgation / d’audit, pas une renonciation à la conformité ; sans elle l’appel est rejeté 422 svg_acceptance_required et rien n’est facturé. La livraison exige aussi que ton organisation ait accepté les ToS/AUP actuels (vérifié côté serveur) ; sinon l’appel est rejeté 403 svg_phase1_scope_out_required sans facturation. Async — interroge get_job_status(kind="image_vectorize", id=…). Coût : 5 sur un miss (chaque moteur et chaque mode) ; 0 sur un cache hit — un résultat en cache ne compte que s’il vient du même engine et du même mode. Scope images.transform.
  • mode (requis) — l’un de :
    • image_to_video — anime une image de départ. Requiert exactement un de image_id / image_url ; end_image_url optionnel sur les moteurs prenant en charge une image de fin ; prompt optionnel.
    • text_to_video — requiert prompt.
    • text_to_video_styled — requiert prompt et style_id ; object_ids / person_ids / setting_ids optionnels, plus une color_palette optionnelle (nom ou id).
  • engine (par défaut veo_3_1_lite), duration (par défaut : la durée la plus courte prise en charge par le moteur, en secondes), aspect_ratio (par défaut "16:9" ; aussi 9:16, 1:1).
  • Kling 4.0 (engine: "kling_4_0") — duration est chaque seconde entière de 3 à 30, par défaut 5. L’outil n’a pas de paramètre resolution, donc la vidéo est en 720p, avec une bande son toujours active : 15 credits par seconde (un clip de 5 s coûte 75). En image_to_video, la vidéo suit le cadrage de l’image de départ. Voir Kling 4.0.
Async — renvoie { id, status: "pending", estimated_credits }. Coût : multiplicateurs 5 / seconde × moteur × résolution × audio ; le mode stylisé ajoute un forfait de 10 pour l’image intermédiaire. Voir tarification.
  • kind (requis) — un de image_generation, image_edit, img2img, image_variation, image_resize, image_upscale, image_background_removal, image_vectorize, video ou model. Utilise le kind que l’outil de soumission t’a indiqué d’interroger.
  • id (requis) — l’id de job ou de modèle qu’un outil de soumission a renvoyé.
Renvoie le statut (pending → processing → completed / failed) et, une fois completed, les URLs de résultat presignées valables 24 heures. Requiert le scope de l’outil de soumission (models.read pour kind: "model").processing signifie « interroge à nouveau ». Pour les kinds d’image image_generation, image_edit, img2img, image_variation et image_resize :
  • Quand tous les outputs ont échoué dans le pipeline de conformité (par exemple la signature C2PA), le job est failed avec error à delivery_blocked_compliance: <codes> et aucune image. C’est terminal — arrête d’interroger.
  • Quand certains outputs seulement y ont échoué, le job est completed : images contient les outputs livrables et blocked_images liste les autres sous la forme { id, reason }. reason vaut compliance_failed_signing, compliance_failed_storage, compliance_failed_watermark ou missing_provenance_state.
Pour un job d’image raster terminé — tout kind d’image sauf image_vectorize — la réponse inclut aussi un aperçu inline réduit, pour que les clients MCP puissent l’afficher directement, en plus du lien vers l’asset en pleine résolution. image_vectorize renvoie un SVG (pas d’aperçu raster) : utilise l’URL presignée. L’aperçu est une copie en résolution réduite pour un affichage rapide ; récupère le lien pour l’original.
Aucun paramètre. Renvoie ce que cette connexion peut dépenser (available et spendable_plan_credits), ainsi que les plan_credits et topup_credits de l’organisation, la période de facturation actuelle et scope — le régime de budget depuis lequel la connexion puise. available peut être inférieur à plan_credits quand l’organisation réserve des credits de plan à des équipes, ce qui explique qu’un job puisse être refusé pour credits insuffisants alors que l’organisation affiche encore un solde. Voir GET /credits pour la sémantique complète des champs.
Les arguments d’un outil MCP ne peuvent pas porter d’octets de fichier. Pour utiliser un fichier image local comme source, uploade-le en trois étapes :
  1. Appelle prepare_image_upload avec :
    • filename (requis) — le nom du fichier.
    • content_type (requis) — image/jpeg, image/png ou image/webp.
    • size_bytes (requis) — la taille exacte du fichier en octets (par exemple via wc -c < photo.png). Elle est signée dans l’URL, donc un PUT de toute autre longueur est rejeté.
    • width, height (optionnels) — servent uniquement à refuser tôt une image de plus de 32 MP.
    Il renvoie { image_id, upload_url, expires_at, max_bytes, allowed_content_types } et une chaîne next_step.
  2. Fais toi-même un PUT des octets bruts du fichier vers upload_url, en dehors de MCP, avec le même Content-Type et sans en-tête Authorization :
  3. Appelle complete_image_upload(image_id) dans l’heure.
Limites : au plus 10 Mo (10 485 760 octets) et 32 mégapixels ; upload_url expire après 1 heure ; au plus 20 uploads en attente de finalisation par utilisateur (too_many_pending_uploads au-delà). L’image appartient à l’utilisateur appelant (le créateur de la clé API ou l’utilisateur OAuth) — les autres membres de ton organisation ne peuvent pas l’utiliser. Gratuit. Scope : l’un de images.edit, images.transform ou videos.generate. Équivalent REST : Téléversement d’images.
  • image_id (requis) — l’id renvoyé par prepare_image_upload.
Appelle-le après le PUT. Vérifie le fichier stocké (présent, exactement size_bytes, au plus 10 Mo, une image lisible du content_type préparé, au plus 32 mégapixels) et renvoie { image_id, status: "completed", filename, content_type, size_bytes, width, height }. Synchrone — l’image_id est utilisable tout de suite comme source de edit_image, img2img, upscale_image, resize_image, create_variations, remove_background, vectorize_image et generate_video (mode: "image_to_video"). Tant que cet appel n’a pas réussi, l’image_id n’est utilisable nulle part.Tu peux le rappeler sans risque : il renvoie le même résultat, et un PUT ultérieur ne modifie pas l’image finalisée. Un fichier qui échoue à une vérification renvoie une erreur de validation et est supprimé — fais un PUT d’un fichier valide vers la même upload_url tant qu’elle est valide et rappelle cet outil. Un image_id inconnu, expiré ou appartenant à un autre utilisateur renvoie not_found ; upload_in_progress signifie qu’un autre appel est en train de le finaliser — rappelle dans quelques secondes. Gratuit. Mêmes scopes que prepare_image_upload.