Skip to main content
Le server expose quinze outils. Six sont gratuits — les quatre lectures (list_models, get_model, get_job_status, get_credit_balance) et les deux outils de gestion de modèles (create_model, update_model). Les neuf autres coûtent des credits du pool de ton organisation, aux mêmes tarifs que l’app et l’API REST.
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.
  • 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 soit un data URI base64 inline (data:image/png;base64,…) — image/jpeg, image/png ou image/webp, ≤ 10 Mo chacune.
  • 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 sont réservés au REST (non exposés via MCP) — utilise POST /models/prepare pour cela.
  • 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.
  • prompt (requis) — le prompt texte.
  • 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" ; 1K / 2K / 4K).
aspect_ratio accepte 1:1 (par défaut), 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8 et 8:1.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.
  • prompt (requis) — comment éditer l’image.
  • Exactement un de image_id (une image de ton contexte Samsa) ou image_url (une URL https publique).
  • 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.
  • engine (optionnel) — nano_banana_pro (par défaut), gemini ou kontext. Fournir une référence de modèle entraîné ou une palette de couleurs force nano_banana_pro.
Async — renvoie { id, status: "pending", estimated_credits }. Coût : 5 credits par output (nano_banana_pro est mis à l’échelle selon la résolution : 1K ×1, 2K ×2, 4K ×4), déduit à la soumission.
  • 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) ou nano_banana_2.
  • aspect_ratio (optionnel) — validé contre la liste du moteur (nano_banana_2 autorise 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).
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 ; 0 sur un cache hit. 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).
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").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.