> ## Documentation Index > Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt > Use this file to discover all available pages before exploring further. # Outils MCP > Chaque outil du MCP server de Samsa, avec ses paramètres, le scope requis et son coût en credits. 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](/fr/guides/pricing) du pool de ton organisation, aux mêmes tarifs que l'app et l'API REST. | Outil | Ce qu'il fait | Scope | Coût | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | ----------------------------------------- | | `list_models` | Liste les modèles entraînés prêts de ton organisation (id, nom, catégorie, thumbnail). | `models.read` | Gratuit | | `get_model` | Détail complet d'un modèle — statut, images de référence, prompt par défaut, mots déclencheurs. | `models.read` | Gratuit | | `create_model` | Entraîne un nouveau modèle à partir de 1–10 images de référence (async). | `models.write` | Gratuit | | `update_model` | Met à jour le nom, le prompt par défaut et/ou l'instruction toujours appliquée d'un modèle. | `models.write` | Gratuit | | `generate_image` | Génère des images à partir d'un prompt, en composant éventuellement tes modèles entraînés. | `images.generate` | 5 × outputs × résolution | | `edit_image` | Magic Edit — édite une image à partir d'un prompt. | `images.edit` | 5 par output | | `img2img` | Transforme 1–14 images de référence à partir d'un prompt. | `images.edit` | 5 × outputs × résolution | | `create_variations` | Génère des variations créatives d'une image. | `images.transform` | 5 × outputs × résolution source | | `resize_image` | Redimensionne vers un nouveau ratio par outpainting. | `images.transform` | 5 × outputs × résolution | | `upscale_image` | Upscale une image en plus haute résolution (quatre modèles). | `images.transform` | Palier × multiplicateur du modèle | | `remove_background` | Supprime l'arrière-plan (PNG transparent). | `images.transform` | 1 (0 sur un cache hit) | | `vectorize_image` | Vectorise une image en SVG. | `images.transform` | 5 (0 sur un cache hit) | | `generate_video` | Génère de la vidéo à partir d'une image de départ, à partir de texte, ou à partir de texte stylisé avec tes modèles. | `videos.generate` | 5 / seconde × moteur × résolution × audio | | `get_job_status` | Interroge un job d'image, de transformation, de vidéo ou de modèle soumis pour son statut et ses résultats. | scope de l'outil de soumission | Gratuit | | `get_credit_balance` | Lit le solde de credits que cette connexion peut dépenser, les totaux de l'organisation, son scope de budget et la période de facturation. | `usage.read` | Gratuit | 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](/fr/api-reference/model-training/overview). * `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`](/fr/api-reference/model-training/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](/fr/guides/image-inputs). * `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](/fr/guides/pricing#upscale). 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](/fr/guides/content-provenance). 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](/fr/guides/pricing#génération-de-vidéos). * `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`](/fr/api-reference/account/credits) pour la sémantique complète des champs.