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.
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.Parametri
list_models(category?)
list_models(category?)
category(facoltativo) — filtra a uno trastyle,object,person,setting.
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.get_model(model_id)
get_model(model_id)
model_id(obbligatorio) — l’id del modello.
create_model(name, category, images, …)
create_model(name, category, images, …)
name(obbligatorio) — il nome del modello.category(obbligatorio) — uno trastyle,object,person,setting.images(obbligatorio) — 1–10 immagini di riferimento. Ciascuna è o un URLhttpspubblico (≤ 10 MB ciascuna) oppure un data URI base64 inline (data:image/png;base64,…) —image/jpeg,image/pngoimage/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 URLhttps.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 URLhttpsnotificato una volta quando l’addestramento raggiunge uno stato terminale.
{ 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.update_model(model_id, …)
update_model(model_id, …)
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.
name, default_prompt o instruction; i campi
omessi restano invariati. Sincrono — restituisce subito il modello aggiornato
completo (stessa forma di get_model). Gratis.list_image_engines()
list_image_engines()
{ 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.improve_prompt(prompt, target, …) — in arrivo
improve_prompt(prompt, target, …) — in arrivo
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) —imageovideo: il mezzo a cui è destinato il prompt migliorato.language(facoltativo) — un tag di lingua BCP-47 comeenodeper 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 restituisceidempotency_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 RESTIdempotency-Key.
{ 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.generate_image(prompt, …)
generate_image(prompt, …)
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_4oflux_1_pro. Omettilo per usarenano_banana_pro. I limiti di ogni engine sono in Engine, oppure chiamalist_image_engines.style_id,object_ids,person_ids,setting_ids(facoltativi) — id o nomi dei modelli addestrati dalist_modelsda 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, predefinito1),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.edit_image(prompt, …)
edit_image(prompt, …)
prompt(obbligatorio) — come modificare l’immagine.- Esattamente uno tra
image_id(un’immagine nel tuo contesto Samsa, per esempio dacomplete_image_upload) oimage_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) okontext(Flux Kontext). Un engine sconosciuto restituisce422con i valori validi. Vedi Engine e credits.resolution(facoltativo) —1K(predefinito),2Ko4Ksunano_banana_pro,nano_banana_2enano_banana_2_1.geminiekontexthanno una risoluzione fissa: lì omettiresolution(un valore restituisce422).num_images(facoltativo) —1–4, predefinito1.style_id,object_ids,person_ids,setting_ids(facoltativi) — id o nomi dei modelli addestrati dalist_modelsda riusare per modifiche fedeli al tuo brand (un nome viene risolto a un modello visibile a te), alla pari congenerate_image.color_palette(facoltativo) — una palette di colori da applicare, indicata con il suo nome o id.
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.img2img(prompt, images, …)
img2img(prompt, images, …)
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_2onano_banana_2_1(Nano Banana 2.1).aspect_ratio(facoltativo) — validato rispetto alla lista dell’engine (nano_banana_2enano_banana_2_1consentono anche4:1,1:4,8:1,1:8); se omesso, la forma della sorgente è preservata.resolution(1Kpredefinito,2K,4K),num_outputs(predefinito1).
get_job_status(kind="img2img", id=…). Costo:
5 × num_outputs × risoluzione (1K ×1, 2K ×2, 4K ×4). Scope
images.edit.create_variations(image_id | image_url, …)
create_variations(image_id | image_url, …)
- Uno tra
image_idoimage_url(obbligatorio). target(facoltativo) — cosa può cambiare:everything(predefinito),person,object,scene.creativity(facoltativo) —subtleocreative(predefinito).variation_instructions/preservation_instructions(facoltativi) — testo libero, ≤ 2000 caratteri ciascuno.num_outputs(1–4, predefinito1).
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.resize_image(aspect_ratio, image_id | image_url, …)
resize_image(aspect_ratio, image_id | image_url, …)
aspect_ratio(obbligatorio) — uno tra21:9,16:9,3:2,4:3,5:4,1:1,4:5,3:4,2:3,9:16.- Uno tra
image_idoimage_url(obbligatorio). resolution(1Kpredefinito,2K,4K),num_outputs(1–4, predefinito1).prompt(facoltativo) — guida per l’area appena esposta.placement(facoltativo) —{ gravity, scale }che posiziona la sorgente sul canvas (gravityuno tracenter[predefinito],top,bottom,left,right,top_left,top_right,bottom_left,bottom_right;scalein(0, 1]).
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.upscale_image(target_resolution, image_id | image_url, …)
upscale_image(target_resolution, image_id | image_url, …)
target_resolution(obbligatorio) —2K,4K,6K,8K,10K,12K,14K,16K,20K,24K,28K,32K,38K(le classi oltre16Ksono solocrystal).- Uno tra
image_idoimage_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/fractalityin −10..10,engine) ooptions.magnific_precision(sharpen/smart_grain/ultra_detailin 0..100,flavor).seedvr/crystalnon prendono opzioni.
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.remove_background(image_id | image_url)
remove_background(image_id | image_url)
- Uno tra
image_idoimage_url(obbligatorio).
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.vectorize_image(svg_acceptance, image_id | image_url)
vectorize_image(svg_acceptance, image_id | image_url)
svg_acceptance(obbligatorio) — deve essere il booleano letteraletrue.- Uno tra
image_idoimage_url(obbligatorio). engine(facoltativo, predefinitorecraft) —recraftoideogram.mode(facoltativo) —default(dettagliato, il predefinito) osimple. Valido solo conengine: "ideogram"; ogni altra combinazione è rifiutata422senza addebito.
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.generate_video(mode, …)
generate_video(mode, …)
mode(obbligatorio) — uno tra:image_to_video— anima un frame iniziale. Richiede esattamente uno traimage_id/image_url;end_image_urlfacoltativo su engine capaci di gestire il frame finale;promptfacoltativo.text_to_video— richiedeprompt.text_to_video_styled— richiedepromptestyle_id;object_ids/person_ids/setting_idsfacoltativi, più unacolor_palettefacoltativa (nome o id).
engine(predefinitoveo_3_1_lite),duration(predefinito: la durata più breve supportata dall’engine, in secondi),aspect_ratio(predefinito"16:9"; anche9:16,1:1).- Kling 4.0 (
engine: "kling_4_0") —durationè ogni secondo intero da3a30, predefinito5. Il tool non ha un parametroresolution, quindi il video è a720p, con una colonna sonora sempre attiva: 15 credits al secondo (una clip di 5 s costa75). Inimage_to_videoil video segue l’inquadratura dell’immagine iniziale. Consulta Kling 4.0.
{ 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.get_job_status(kind, id)
get_job_status(kind, id)
kind(obbligatorio) — uno traimage_generation,image_edit,img2img,image_variation,image_resize,image_upscale,image_background_removal,image_vectorize,videoomodel. 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.
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 è
failedconerrorimpostato adelivery_blocked_compliance: <codes>e nessuna immagine. È uno stato terminale — smetti di interrogare. - Quando solo alcuni output non l’hanno superata, il job è
completed:imagescontiene gli output consegnabili eblocked_imageselenca gli altri come{ id, reason }.reasonècompliance_failed_signing,compliance_failed_storage,compliance_failed_watermarkomissing_provenance_state.
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.get_credit_balance()
get_credit_balance()
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.prepare_image_upload(filename, content_type, size_bytes, …)
prepare_image_upload(filename, content_type, size_bytes, …)
-
Chiama
prepare_image_uploadcon:filename(obbligatorio) — il nome del file.content_type(obbligatorio) —image/jpeg,image/pngoimage/webp.size_bytes(obbligatorio) — la dimensione esatta del file in byte (per esempio dawc -c < photo.png). È firmata nell’URL, quindi unPUTdi qualsiasi altra lunghezza viene rifiutato.width,height(facoltativi) — usati solo per rifiutare in anticipo un’immagine oltre i 32 MP.
{ image_id, upload_url, expires_at, max_bytes, allowed_content_types }e una stringanext_step. -
Fai tu il
PUTdei byte grezzi del file suupload_url, fuori da MCP, con lo stessoContent-Typee senza headerAuthorization: -
Chiama
complete_image_upload(image_id)entro un’ora.
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.complete_image_upload(image_id)
complete_image_upload(image_id)
image_id(obbligatorio) — l’id restituito daprepare_image_upload.
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.