Vai al contenuto principale
Il server espone diciotto strumenti. Nove sono gratuiti — le cinque letture (list_models, get_model, list_image_engines, get_job_status, get_credit_balance), i due strumenti di gestione dei modelli (create_model, update_model) e i due strumenti di upload (prepare_image_upload, complete_image_upload). Gli altri nove costano credits dal pool della tua organizzazione, alle stesse tariffe dell’app e della REST API.
In arrivo: improve_prompt, un diciannovesimo strumento che costa 1 credit per chiamata. Non è ancora nell’elenco degli strumenti del server; vi compare non appena il miglioramento dei prompt viene attivato. La sua riga e la sua sezione qui sotto lo descrivono come sarà al lancio.
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. Gli engine text-to-image generali non sono modelli addestrati — list_image_engines li elenca.
  • 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 (≤ 10 MB ciascuna) oppure un data URI base64 inline (data:image/png;base64,…) — image/jpeg, image/png o image/webp. L’intera richiesta MCP è limitata a 1 MB, quindi le immagini base64 inline possono trasportare solo circa 750 KB di dati in totale — invia le immagini più grandi come URL https.
  • 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 modelli con file di grandi dimensioni sono solo REST (non esposti via MCP) — usa POST /models/prepare per quelli. Un image_id di prepare_image_upload non è accettato qui.
  • 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.
Nessun parametro. Restituisce { data: [...], unavailable_reason } — una voce per ogni engine text-to-image che puoi usare, con il predefinito per primo: id, name, is_default, provider_family, aspect_ratios, default_aspect_ratio, resolutions, default_resolution, max_num_outputs, credits_per_image (per risoluzione; una richiesta costa questo valore × num_outputs), supports_trained_refs e supports_color_palette. Il contenuto è lo stesso di GET /images/models. Passa l’id di una voce come engine a generate_image.Se la tua organizzazione genera solo con i suoi modelli addestrati, data è vuoto e unavailable_reason è organization_restricted; altrimenti è null. Gratuito. Scope images.generate.
In arrivo — non compare nell’elenco degli strumenti del server finché il miglioramento dei prompt non viene attivato.
  • prompt (obbligatorio) — il prompt da migliorare: da 3 a 5000 caratteri dopo la rimozione degli spazi iniziali e finali, con le stesse regole di ogni prompt Samsa (niente < o >, niente backslash, niente a capo o tabulazioni).
  • target (obbligatorio) — image o video: il mezzo a cui è destinato il prompt migliorato.
  • language (facoltativo) — un tag di lingua BCP-47 come en o de per la lingua del prompt migliorato. Omesso: il prompt migliorato mantiene la lingua del tuo prompt.
  • idempotency_key (facoltativo) — da 1 a 255 caratteri ASCII stampabili. La stessa chiave con gli stessi argomenti entro 24 ore restituisce il risultato salvato e non viene mai addebitata due volte; la stessa chiave con altri argomenti viene rifiutata (idempotency_key_reused), e una chiave la cui prima chiamata è ancora in corso restituisce idempotency_in_progress. Una chiave la cui chiamata è fallita restituisce di nuovo quell’errore: usa una nuova chiave per un nuovo tentativo a pagamento. Le chiavi valgono per il titolare delle credenziali (il creatore della chiave API o l’utente OAuth) all’interno dell’organizzazione e condividono un unico namespace con l’header REST Idempotency-Key.
Sincrono — restituisce direttamente { improved_prompt, target, language, credits_charged }; non c’è nessun job da interrogare. Passa improved_prompt come prompt a generate_image o generate_video. Costo: 1 credit per chiamata, addebitato prima che il modello venga eseguito; se il provider di IA fallisce, il credit viene rimborsato e lo strumento restituisce un provider_error. Gli errori hanno la stessa forma strutturata di errore degli altri strumenti. Scope: uno tra images.generate, images.edit o videos.generate. Equivalente REST: POST /prompts/improve.
  • prompt (obbligatorio) — il prompt testuale.
  • engine (facoltativo) — il modello text-to-image: nano_banana_pro (predefinito), nano_banana_2_1, nano_banana_2, nano_banana, imagen_4, seedream_4 o flux_1_pro. Omettilo per usare nano_banana_pro. I limiti di ogni engine sono in Engine, oppure chiama list_image_engines.
  • 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").
aspect_ratio e resolution vengono validati rispetto all’engine: nano_banana_pro, nano_banana_2_1 e nano_banana_2 accettano 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 a 1K / 2K / 4K; nano_banana i primi dieci di questi a 1K; imagen_4 1:1, 16:9, 9:16, 4:3, 3:4 a 1K / 2K; seedream_4 e flux_1_pro 1:1, 16:9, 9:16, 4:3, 3:4, 21:9 a 1K. Un engine sconosciuto o un valore non supportato restituisce un 422 che indica i valori validi.I modelli addestrati e color_palette funzionano solo con nano_banana_pro, nano_banana_2_1 e nano_banana_2; su qualsiasi altro engine restituiscono 422 — non vengono mai scartati, e l’engine non viene mai cambiato. Alcune organizzazioni generano solo con i loro modelli addestrati: lì qualsiasi engine restituisce 422 — ometti engine e passa almeno un modello addestrato o una color_palette.Asincrono — restituisce { id, status: "pending", estimated_credits } immediatamente. Costo: 5 × num_outputs × risoluzione (1K ×1, 2K ×2, 4K ×4), dedotto all’invio — uguale su ogni engine.
  • prompt (obbligatorio) — come modificare l’immagine.
  • Esattamente uno tra image_id (un’immagine nel tuo contesto Samsa, per esempio da complete_image_upload) o image_url (un URL https pubblico). Il rapporto d’aspetto della sorgente viene mantenuto.
  • engine (facoltativo) — nano_banana_pro (Nano Banana Pro, predefinito), nano_banana_2 (Nano Banana 2), nano_banana_2_1 (Nano Banana 2.1), gemini (Nano Banana via FAL) o kontext (Flux Kontext). Un engine sconosciuto restituisce 422 con i valori validi. Vedi Engine e credits.
  • resolution (facoltativo) — 1K (predefinito), 2K o 4K su nano_banana_pro, nano_banana_2 e nano_banana_2_1. gemini e kontext hanno una risoluzione fissa: lì ometti resolution (un valore restituisce 422).
  • num_images (facoltativo) — 1–4, predefinito 1.
  • 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.
I modelli addestrati e color_palette funzionano solo con nano_banana_pro (anche quando ometti engine). Indicare un qualsiasi altro engine insieme a loro restituisce 422 prima di qualsiasi addebito — l’engine non viene mai cambiato. Le modifiche con maschera sono solo REST e girano su nano_banana_pro o gemini.Asincrono — restituisce { id, status: "pending", estimated_credits, engine, resolution }. engine e resolution sono i valori effettivi con cui gira la modifica (resolution è null su gemini e kontext). Costo per output: 5 credits × risoluzione sui tre engine Nano Banana (1K 5, 2K 10, 4K 20), 5 fissi su gemini e kontext; × num_images, dedotto all’invio. Per esempio, edit_image(prompt=…, image_id=…, resolution="4K") restituisce estimated_credits: 20.
  • 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), nano_banana_2 o nano_banana_2_1 (Nano Banana 2.1).
  • aspect_ratio (facoltativo) — validato rispetto alla lista dell’engine (nano_banana_2 e nano_banana_2_1 consentono 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).
  • engine (facoltativo, predefinito recraft) — recraft o ideogram.
  • mode (facoltativo) — default (dettagliato, il predefinito) o simple. Valido solo con engine: "ideogram"; ogni altra combinazione è rifiutata 422 senza addebito.
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 (ogni engine e ogni mode); 0 con un cache hit — un risultato in cache conta solo se viene dallo stesso engine e dallo stesso mode. 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).
  • Kling 4.0 (engine: "kling_4_0") — duration è ogni secondo intero da 3 a 30, predefinito 5. Il tool non ha un parametro resolution, quindi il video è a 720p, con una colonna sonora sempre attiva: 15 credits al secondo (una clip di 5 s costa 75). In image_to_video il video segue l’inquadratura dell’immagine iniziale. Consulta Kling 4.0.
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").processing significa “interroga di nuovo”. Per i kind di immagine image_generation, image_edit, img2img, image_variation e image_resize:
  • Quando tutti gli output non hanno superato la pipeline di compliance (per esempio la firma C2PA), il job è failed con error impostato a delivery_blocked_compliance: <codes> e nessuna immagine. È uno stato terminale — smetti di interrogare.
  • Quando solo alcuni output non l’hanno superata, il job è completed: images contiene gli output consegnabili e blocked_images elenca gli altri come { id, reason }. reason è compliance_failed_signing, compliance_failed_storage, compliance_failed_watermark o missing_provenance_state.
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.
Gli argomenti degli strumenti MCP non possono trasportare i byte di un file. Per usare un file immagine locale come sorgente, caricalo in tre passaggi:
  1. Chiama prepare_image_upload con:
    • filename (obbligatorio) — il nome del file.
    • content_type (obbligatorio) — image/jpeg, image/png o image/webp.
    • size_bytes (obbligatorio) — la dimensione esatta del file in byte (per esempio da wc -c < photo.png). È firmata nell’URL, quindi un PUT di qualsiasi altra lunghezza viene rifiutato.
    • width, height (facoltativi) — usati solo per rifiutare in anticipo un’immagine oltre i 32 MP.
    Restituisce { image_id, upload_url, expires_at, max_bytes, allowed_content_types } e una stringa next_step.
  2. Fai tu il PUT dei byte grezzi del file su upload_url, fuori da MCP, con lo stesso Content-Type e senza header Authorization:
  3. Chiama complete_image_upload(image_id) entro un’ora.
Limiti: al massimo 10 MB (10,485,760 byte) e 32 megapixel; upload_url scade dopo 1 ora; al massimo 20 upload in attesa di completamento per utente (too_many_pending_uploads oltre). L’immagine appartiene all’utente chiamante (il creatore della chiave API o l’utente OAuth) — gli altri membri della tua organizzazione non possono usarla. Gratis. Scope: uno qualsiasi tra images.edit, images.transform o videos.generate. Equivalente REST: Caricamento di immagini.
  • image_id (obbligatorio) — l’id restituito da prepare_image_upload.
Chiamalo dopo il PUT. Verifica il file salvato (presente, esattamente size_bytes, al massimo 10 MB, un’immagine leggibile del content_type preparato, al massimo 32 megapixel) e restituisce { image_id, status: "completed", filename, content_type, size_bytes, width, height }. Sincrono — l’image_id è subito utilizzabile come sorgente di edit_image, img2img, upscale_image, resize_image, create_variations, remove_background, vectorize_image e generate_video (mode: "image_to_video"). Prima che questa chiamata riesca, l’image_id non è utilizzabile da nessuna parte.Puoi richiamarlo senza rischi: restituisce lo stesso risultato, e un PUT successivo non modifica l’immagine completata. Un file che non supera un controllo restituisce un errore di validazione e viene scartato — fai il PUT di un file valido sullo stesso upload_url finché è ancora valido e richiama questo strumento. Un image_id sconosciuto, scaduto o di un altro utente restituisce not_found; upload_in_progress significa che un’altra chiamata lo sta completando proprio ora — riprova tra qualche secondo. Gratis. Stessi scope di prepare_image_upload.