Skip to main content
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 dal pool della tua organizzazione, alle stesse tariffe dell’app e della REST API.
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.
  • 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 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.
  • 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. 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. 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.
  • 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 per la semantica completa dei campi.