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.
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.Paramètres
list_models(category?)
list_models(category?)
category(optionnel) — filtre sur l’un destyle,object,person,setting.
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.get_model(model_id)
get_model(model_id)
model_id(requis) — l’id du modèle.
create_model(name, category, images, …)
create_model(name, category, images, …)
name(requis) — le nom du modèle.category(requis) — l’un destyle,object,person,setting.images(requis) — 1–10 images de référence. Chacune est soit une URLhttpspublique (≤ 10 Mo chacune) soit un data URI base64 inline (data:image/png;base64,…) —image/jpeg,image/pngouimage/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’URLshttps.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 URLhttpsnotifiée une fois lorsque l’entraînement atteint un statut terminal.
{ 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.update_model(model_id, …)
update_model(model_id, …)
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.
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.list_image_engines()
list_image_engines()
{ 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.improve_prompt(prompt, target, …) — bientôt disponible
improve_prompt(prompt, target, …) — bientôt disponible
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) —imageouvideo: le média auquel le prompt amélioré est destiné.language(optionnel) — un tag de langue BCP-47 commeenoudepour 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 renvoieidempotency_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 RESTIdempotency-Key.
{ 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.generate_image(prompt, …)
generate_image(prompt, …)
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_4ouflux_1_pro. Omets-le pour utilisernano_banana_pro. Les limites de chaque moteur sont dans Moteurs, ou appellelist_image_engines.style_id,object_ids,person_ids,setting_ids(optionnels) — ids ou noms de modèles entraînés issus delist_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éfaut1),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.edit_image(prompt, …)
edit_image(prompt, …)
prompt(requis) — comment éditer l’image.- Exactement un de
image_id(une image de ton contexte Samsa, par exemple issue decomplete_image_upload) ouimage_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) oukontext(Flux Kontext). Un moteur inconnu renvoie422en nommant les valeurs valides. Voir Engines et credits.resolution(optionnel) —1K(par défaut),2Kou4Ksurnano_banana_pro,nano_banana_2etnano_banana_2_1.geminietkontextont une résolution fixe : ometsresolutionpour eux (une valeur renvoie422).num_images(optionnel) —1–4, par défaut1.style_id,object_ids,person_ids,setting_ids(optionnels) — ids ou noms de modèles entraînés issus delist_modelsà réutiliser pour des éditions fidèles à ta marque (un nom est résolu vers un modèle visible pour toi), à parité avecgenerate_image.color_palette(optionnel) — une palette de couleurs à appliquer, donnée par son nom ou son id.
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.img2img(prompt, images, …)
img2img(prompt, images, …)
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_2ounano_banana_2_1(Nano Banana 2.1).aspect_ratio(optionnel) — validé contre la liste du moteur (nano_banana_2etnano_banana_2_1autorisent en plus4:1,1:4,8:1,1:8) ; omis, la forme de la source est préservée.resolution(1Kpar défaut,2K,4K),num_outputs(par défaut1).
get_job_status(kind="img2img", id=…). Coût :
5 × num_outputs × résolution (1K ×1, 2K ×2, 4K ×4). Scope
images.edit.create_variations(image_id | image_url, …)
create_variations(image_id | image_url, …)
- Un de
image_idouimage_url(requis). target(optionnel) — ce qui peut changer :everything(par défaut),person,object,scene.creativity(optionnel) —subtleoucreative(par défaut).variation_instructions/preservation_instructions(optionnels) — texte libre, ≤ 2000 caractères chacun.num_outputs(1–4, par défaut1).
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.resize_image(aspect_ratio, image_id | image_url, …)
resize_image(aspect_ratio, image_id | image_url, …)
aspect_ratio(requis) — un de21:9,16:9,3:2,4:3,5:4,1:1,4:5,3:4,2:3,9:16.- Un de
image_idouimage_url(requis). resolution(1Kpar défaut,2K,4K),num_outputs(1–4, par défaut1).prompt(optionnel) — guidage pour la zone nouvellement exposée.placement(optionnel) —{ gravity, scale }positionnant la source sur le canevas (gravityun decenter[par défaut],top,bottom,left,right,top_left,top_right,bottom_left,bottom_right;scaledans(0, 1]).
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.upscale_image(target_resolution, image_id | image_url, …)
upscale_image(target_resolution, image_id | image_url, …)
target_resolution(requis) —2K,4K,6K,8K,10K,12K,14K,16K,20K,24K,28K,32K,38K(les classes au-dessus de16Ksont réservées àcrystal).- Un de
image_idouimage_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/fractalitydans −10..10,engine) ouoptions.magnific_precision(sharpen/smart_grain/ultra_detaildans 0..100,flavor).seedvr/crystalne prennent pas d’options.
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.remove_background(image_id | image_url)
remove_background(image_id | image_url)
- Un de
image_idouimage_url(requis).
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.vectorize_image(svg_acceptance, image_id | image_url)
vectorize_image(svg_acceptance, image_id | image_url)
svg_acceptance(requis) — doit être le booléen littéraltrue.- Un de
image_idouimage_url(requis). engine(optionnel, par défautrecraft) —recraftouideogram.mode(optionnel) —default(détaillé, par défaut) ousimple. Valide uniquement avecengine: "ideogram"; toute autre combinaison est rejetée422sans facturation.
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.generate_video(mode, …)
generate_video(mode, …)
mode(requis) — l’un de :image_to_video— anime une image de départ. Requiert exactement un deimage_id/image_url;end_image_urloptionnel sur les moteurs prenant en charge une image de fin ;promptoptionnel.text_to_video— requiertprompt.text_to_video_styled— requiertpromptetstyle_id;object_ids/person_ids/setting_idsoptionnels, plus unecolor_paletteoptionnelle (nom ou id).
engine(par défautveo_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"; aussi9:16,1:1).- Kling 4.0 (
engine: "kling_4_0") —durationest chaque seconde entière de3à30, par défaut5. L’outil n’a pas de paramètreresolution, donc la vidéo est en720p, avec une bande son toujours active : 15 credits par seconde (un clip de 5 s coûte75). Enimage_to_video, la vidéo suit le cadrage de l’image de départ. Voir Kling 4.0.
{ 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.get_job_status(kind, id)
get_job_status(kind, id)
kind(requis) — un deimage_generation,image_edit,img2img,image_variation,image_resize,image_upscale,image_background_removal,image_vectorize,videooumodel. 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é.
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
failedavecerrorà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:imagescontient les outputs livrables etblocked_imagesliste les autres sous la forme{ id, reason }.reasonvautcompliance_failed_signing,compliance_failed_storage,compliance_failed_watermarkoumissing_provenance_state.
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.get_credit_balance()
get_credit_balance()
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.prepare_image_upload(filename, content_type, size_bytes, …)
prepare_image_upload(filename, content_type, size_bytes, …)
-
Appelle
prepare_image_uploadavec :filename(requis) — le nom du fichier.content_type(requis) —image/jpeg,image/pngouimage/webp.size_bytes(requis) — la taille exacte du fichier en octets (par exemple viawc -c < photo.png). Elle est signée dans l’URL, donc unPUTde toute autre longueur est rejeté.width,height(optionnels) — servent uniquement à refuser tôt une image de plus de 32 MP.
{ image_id, upload_url, expires_at, max_bytes, allowed_content_types }et une chaînenext_step. -
Fais toi-même un
PUTdes octets bruts du fichier versupload_url, en dehors de MCP, avec le mêmeContent-Typeet sans en-têteAuthorization: -
Appelle
complete_image_upload(image_id)dans l’heure.
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.complete_image_upload(image_id)
complete_image_upload(image_id)
image_id(requis) — l’id renvoyé parprepare_image_upload.
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.