> ## 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. # Strumenti MCP > Ogni strumento del MCP server di Samsa, con parametri, scope richiesto e costo in credits. Il server espone **quindici strumenti**. Sei sono gratuiti — le quattro letture (`list_models`, `get_model`, `get_job_status`, `get_credit_balance`) e i due strumenti di gestione dei modelli (`create_model`, `update_model`). Gli altri **nove** costano [credits](/it/guides/pricing) dal pool della tua organizzazione, alle stesse tariffe dell'app e della REST API. | Strumento | Cosa fa | Scope | Costo | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------ | | `list_models` | Elenca i modelli addestrati pronti della tua organizzazione (id, nome, categoria, thumbnail). | `models.read` | Gratis | | `get_model` | Dettaglio completo di un modello — stato, immagini di riferimento, prompt predefinito, trigger word. | `models.read` | Gratis | | `create_model` | Addestra un nuovo modello da 1–10 immagini di riferimento (async). | `models.write` | Gratis | | `update_model` | Aggiorna nome, prompt predefinito e/o l'istruzione sempre applicata di un modello. | `models.write` | Gratis | | `generate_image` | Genera immagini da un prompt, componendo facoltativamente i tuoi modelli addestrati. | `images.generate` | 5 × output × risoluzione | | `edit_image` | Magic Edit — modifica un'immagine da un prompt. | `images.edit` | 5 per output | | `img2img` | Trasforma 1–14 immagini di riferimento con un prompt. | `images.edit` | 5 × output × risoluzione | | `create_variations` | Genera variazioni creative di un'immagine. | `images.transform` | 5 × output × risoluzione sorgente | | `resize_image` | Ridimensiona a un nuovo rapporto d'aspetto per outpainting. | `images.transform` | 5 × output × risoluzione | | `upscale_image` | Fa l'upscale di un'immagine a una risoluzione più alta (quattro modelli). | `images.transform` | Fascia × moltiplicatore del modello | | `remove_background` | Rimuove lo sfondo (PNG trasparente). | `images.transform` | 1 (0 con un cache hit) | | `vectorize_image` | Vettorializza un'immagine in SVG. | `images.transform` | 5 (0 con un cache hit) | | `generate_video` | Genera video da un frame iniziale, da testo o da testo stilizzato con i tuoi modelli. | `videos.generate` | 5 / secondo × engine × risoluzione × audio | | `get_job_status` | Interroga un job di immagine, trasformazione, video o modello inviato per stato e risultati. | scope dello strumento che ha inviato | Gratis | | `get_credit_balance` | Leggi il saldo credits che questa connessione può spendere, i totali dell'organizzazione, il suo scope di budget e il periodo di fatturazione. | `usage.read` | Gratis | Una chiamata a uno strumento rifiutata per uno scope mancante restituisce un errore strutturato dello strumento (non un crash) che nomina lo scope di cui ha bisogno. Le chiavi vengono create con tutti gli scope per impostazione predefinita; un admin può restringere o ampliare una chiave in **Settings → API Keys**. ## Parametri * `category` *(facoltativo)* — filtra a uno tra `style`, `object`, `person`, `setting`. Restituisce i modelli **pronti** della tua organizzazione con `id`, `name`, `category` e un `thumbnail_url` presigned. Usa gli id o i nomi come `style_id` / `object_ids` / `person_ids` / `setting_ids` in `generate_image` e `generate_video` — un nome viene risolto a un modello visibile a te. * `model_id` *(obbligatorio)* — l'id del modello. Restituisce il dettaglio completo: stato, prontezza, URL presigned delle immagini di riferimento, il prompt predefinito e le trigger word. * `name` *(obbligatorio)* — il nome del modello. * `category` *(obbligatorio)* — uno tra `style`, `object`, `person`, `setting`. * `images` *(obbligatorio)* — 1–10 immagini di riferimento. Ciascuna è **o** un URL `https` pubblico **oppure** un data URI base64 inline (`data:image/png;base64,…`) — `image/jpeg`, `image/png` o `image/webp`, ≤ 10 MB ciascuna. * `instruction` *(facoltativo)* — la guida sempre applicata del modello (≤ 8000 caratteri), iniettata come direttiva obbligatoria ("MUST FOLLOW") in ogni generazione che compone il modello. Vedi [Addestramento di modelli](/it/api-reference/model-training/overview). * `webhook_url` *(facoltativo)* — un URL `https` notificato una volta quando l'addestramento raggiunge uno stato terminale. **Asincrono** — restituisce subito `{ id, status: "pending", estimated_credits }`; interroga `get_job_status(kind="model", id=…)` (che richiede anche lo scope `models.read`) finché non è `completed` o `failed`, poi usa l'id del modello in `generate_image` / `generate_video`. **Gratis** — la creazione del modello non deduce credits. Gli upload presigned di file di grandi dimensioni sono solo REST (non esposti via MCP) — usa [`POST /models/prepare`](/it/api-reference/model-training/prepare) per quelli. * `model_id` *(obbligatorio)* — il modello da aggiornare. * `name` *(facoltativo)* — un nuovo nome del modello. * `default_prompt` *(facoltativo)* — un nuovo prompt predefinito. * `instruction` *(facoltativo)* — la guida sempre applicata del modello (≤ 8000 caratteri). Invia una stringa vuota per cancellarla. Fornisci **almeno uno** tra `name`, `default_prompt` o `instruction`; i campi omessi restano invariati. **Sincrono** — restituisce subito il modello aggiornato completo (stessa forma di `get_model`). **Gratis.** * `prompt` *(obbligatorio)* — il prompt testuale. * `style_id`, `object_ids`, `person_ids`, `setting_ids` *(facoltativi)* — id o nomi dei modelli addestrati da `list_models` da comporre (un nome viene risolto a un modello visibile a te). * `color_palette` *(facoltativo)* — una palette di colori da applicare, indicata con il suo **nome o id** (come i riferimenti ai modelli addestrati). * `num_outputs` (`1`–`4`, predefinito `1`), `aspect_ratio` (predefinito `"1:1"`), `resolution` (predefinito `"1K"`; `1K` / `2K` / `4K`). `aspect_ratio` accetta `1:1` (predefinito), `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `1:4`, `4:1`, `1:8` e `8:1`. **Asincrono** — restituisce `{ id, status: "pending", estimated_credits }` immediatamente. Costo: `5 × num_outputs × risoluzione` (`1K` ×1, `2K` ×2, `4K` ×4), dedotto all'invio. * `prompt` *(obbligatorio)* — come modificare l'immagine. * Esattamente **uno** tra `image_id` (un'immagine nel tuo contesto Samsa) o `image_url` (un URL https pubblico). * `style_id`, `object_ids`, `person_ids`, `setting_ids` *(facoltativi)* — id o nomi dei modelli addestrati da `list_models` da riusare per modifiche fedeli al tuo brand (un nome viene risolto a un modello visibile a te), alla pari con `generate_image`. * `color_palette` *(facoltativo)* — una palette di colori da applicare, indicata con il suo **nome o id**. * `engine` *(facoltativo)* — `nano_banana_pro` (predefinito), `gemini` o `kontext`. Fornire un qualsiasi riferimento a un modello addestrato o una palette di colori forza `nano_banana_pro`. **Asincrono** — restituisce `{ id, status: "pending", estimated_credits }`. Costo: 5 credits per output (`nano_banana_pro` scala con la risoluzione: `1K` ×1, `2K` ×2, `4K` ×4), dedotto all'invio. * `prompt` *(obbligatorio)* — come trasformare le sorgenti. * `images` *(obbligatorio)* — **1–14** sorgenti; ogni elemento è **o** `{ image_id }` **o** `{ image_url }` (un URL https). L'ordine delle sorgenti è preservato. Nessun base64 su MCP — vedi [Input immagine](/it/guides/image-inputs). * `engine` *(facoltativo)* — `nano_banana_pro` (predefinito) o `nano_banana_2`. * `aspect_ratio` *(facoltativo)* — validato rispetto alla lista dell'engine (`nano_banana_2` consente anche `4:1`, `1:4`, `8:1`, `1:8`); se omesso, la forma della sorgente è preservata. * `resolution` (`1K` predefinito, `2K`, `4K`), `num_outputs` (predefinito `1`). **Asincrono** — interroga `get_job_status(kind="img2img", id=…)`. Costo: `5 × num_outputs × risoluzione` (`1K` ×1, `2K` ×2, `4K` ×4). Scope `images.edit`. * **Uno** tra `image_id` o `image_url` *(obbligatorio)*. * `target` *(facoltativo)* — cosa può cambiare: `everything` (predefinito), `person`, `object`, `scene`. * `creativity` *(facoltativo)* — `subtle` o `creative` (predefinito). * `variation_instructions` / `preservation_instructions` *(facoltativi)* — testo libero, ≤ 2000 caratteri ciascuno. * `num_outputs` (`1`–`4`, predefinito `1`). La **risoluzione di output è ereditata dalla sorgente** (nessun argomento `resolution`). **Asincrono** — interroga `get_job_status(kind="image_variation", id=…)`. Costo: `5 × num_outputs × risoluzione sorgente` (`1K` ×1, `2K` ×2, `4K` ×4; una sorgente senza dimensioni recuperabili è addebitata a `1K`). Scope `images.transform`. * `aspect_ratio` *(obbligatorio)* — uno tra `21:9`, `16:9`, `3:2`, `4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `2:3`, `9:16`. * **Uno** tra `image_id` o `image_url` *(obbligatorio)*. * `resolution` (`1K` predefinito, `2K`, `4K`), `num_outputs` (`1`–`4`, predefinito `1`). * `prompt` *(facoltativo)* — guida per l'area appena esposta. * `placement` *(facoltativo)* — `{ gravity, scale }` che posiziona la sorgente sul canvas (`gravity` uno tra `center` \[predefinito], `top`, `bottom`, `left`, `right`, `top_left`, `top_right`, `bottom_left`, `bottom_right`; `scale` in `(0, 1]`). Ridimensiona per outpainting — il server riempie il nuovo canvas con un'estensione coerente con lo stile. Se non c'è nulla di nuovo da generare e non è fornito alcun `prompt`, restituisce l'immagine appiattita e rimborsa gli output inutilizzati. **Asincrono** — interroga `get_job_status(kind="image_resize", id=…)`. Costo: `5 × num_outputs × risoluzione`. Scope `images.transform`. * `target_resolution` *(obbligatorio)* — `2K`, `4K`, `6K`, `8K`, `10K`, `12K`, `14K`, `16K`, `20K`, `24K`, `28K`, `32K`, `38K` (le classi oltre `16K` sono **solo `crystal`**). * **Uno** tra `image_id` o `image_url` *(obbligatorio)*. * `model` *(facoltativo)* — `seedvr`, `crystal` (predefinito), `magnific-creative`, `magnific-precision`. * `options` *(facoltativo)* — per modello, validate rigorosamente: `options.magnific_creative` (`prompt`, `optimized_for`, `creativity`/`hdr`/`resemblance`/`fractality` in −10..10, `engine`) o `options.magnific_precision` (`sharpen`/`smart_grain`/`ultra_detail` in 0..100, `flavor`). `seedvr`/`crystal` non prendono opzioni. I limiti di fattore/area per modello sono validati **prima** dell'addebito. **Asincrono** — interroga `get_job_status(kind="image_upscale", id=…)`. Costo: la fascia di risoluzione × il moltiplicatore del modello (Magnific ×3); `crystal` oltre `12K` è addebitato in base ai megapixel di output — vedi [prezzi](/it/guides/pricing#upscale). Scope `images.transform`. * **Uno** tra `image_id` o `image_url` *(obbligatorio)*. Produce un PNG trasparente; non c'è un parametro del modello. **Asincrono** — interroga `get_job_status(kind="image_background_removal", id=…)`. Costo: **1** credit su un miss; **0** con un cache hit — un `image_id` che possiedi e che ha già un risultato di rimozione dello sfondo restituisce subito `{ status: "completed", estimated_credits: 0 }`. Scope `images.transform`. * `svg_acceptance` *(obbligatorio)* — deve essere il booleano letterale `true`. * **Uno** tra `image_id` o `image_url` *(obbligatorio)*. Produce un **SVG**. Un SVG non può contenere né un manifesto C2PA né una filigrana, quindi l'output vettoriale è consegnato senza firma — vedi [Provenienza dei contenuti](/it/guides/content-provenance). Il riconoscimento è una prova di divulgazione / audit, non una rinuncia alla conformità; senza di esso la chiamata è rifiutata `422 svg_acceptance_required` e nulla viene addebitato. La consegna richiede inoltre che la tua organizzazione abbia accettato gli attuali ToS/AUP (verificato lato server); in caso contrario la chiamata è rifiutata `403 svg_phase1_scope_out_required` senza addebito. **Asincrono** — interroga `get_job_status(kind="image_vectorize", id=…)`. Costo: **5** su un miss; **0** con un cache hit. Scope `images.transform`. * `mode` *(obbligatorio)* — uno tra: * `image_to_video` — anima un frame iniziale. Richiede esattamente uno tra `image_id` / `image_url`; `end_image_url` facoltativo su engine capaci di gestire il frame finale; `prompt` facoltativo. * `text_to_video` — richiede `prompt`. * `text_to_video_styled` — richiede `prompt` **e** `style_id`; `object_ids` / `person_ids` / `setting_ids` facoltativi, più una `color_palette` facoltativa (nome o id). * `engine` *(predefinito `veo_3_1_lite`)*, `duration` *(predefinito: la durata più breve supportata dall'engine, in secondi)*, `aspect_ratio` *(predefinito `"16:9"`; anche `9:16`, `1:1`)*. **Asincrono** — restituisce `{ id, status: "pending", estimated_credits }`. Costo: moltiplicatori `5 / secondo × engine × risoluzione × audio`; la modalità stilizzata aggiunge un forfait di 10 per l'immagine intermedia. Consulta [prezzi](/it/guides/pricing#generazione-di-video). * `kind` *(obbligatorio)* — uno tra `image_generation`, `image_edit`, `img2img`, `image_variation`, `image_resize`, `image_upscale`, `image_background_removal`, `image_vectorize`, `video` o `model`. Usa il kind che lo strumento di invio ti ha indicato di interrogare. * `id` *(obbligatorio)* — l'id del job o del modello restituito da uno strumento di invio. Restituisce lo stato (`pending` → `processing` → `completed` / `failed`) e, una volta `completed`, gli URL presigned del risultato validi per 24 ore. Richiede lo scope dello strumento che ha inviato (`models.read` per `kind: "model"`). Per un job di **immagine raster** completato — ogni kind di immagine **tranne** `image_vectorize` — la risposta include anche un'**anteprima inline ridimensionata**, così i client MCP possono visualizzarla direttamente, insieme al link all'asset a piena risoluzione. `image_vectorize` restituisce un SVG (nessuna anteprima raster): usa l'URL presigned. L'anteprima è una copia a risoluzione ridotta per una visualizzazione rapida; recupera il link per l'originale. Nessun parametro. Restituisce ciò che **questa connessione** può spendere (`available` e `spendable_plan_credits`), insieme ai `plan_credits` e `topup_credits` a livello di organizzazione, al periodo di fatturazione corrente e a `scope` — il regime di budget da cui la connessione attinge. `available` può essere inferiore a `plan_credits` quando l'organizzazione riserva credits del piano ai team: ecco perché un job può essere rifiutato per credits insufficienti mentre l'organizzazione mostra ancora un saldo. Vedi [`GET /credits`](/it/api-reference/account/credits) per la semantica completa dei campi.