list_models,
get_model, list_image_engines, get_job_status, get_credit_balance), the
two model-management tools (create_model, update_model), and the two upload tools
(prepare_image_upload, complete_image_upload). The other nine cost
credits from your organization’s pool, at the same rates as the
app and REST API.
improve_prompt, a nineteenth tool that costs 1 credit per call.
It is not in the server’s tool list yet; it appears there once prompt improvement
is enabled. Its row and its section below describe it from launch.Parameters
list_models(category?)
list_models(category?)
category(optional) — filter to one ofstyle,object,person,setting.
id, name, category,
and a presigned thumbnail_url. Use the ids or names as style_id /
object_ids / person_ids / setting_ids in generate_image and
generate_video — a name resolves to a model visible to you. The general
text-to-image engines are not trained models — list_image_engines lists them.get_model(model_id)
get_model(model_id)
model_id(required) — the model’s id.
create_model(name, category, images, …)
create_model(name, category, images, …)
name(required) — the model name.category(required) — one ofstyle,object,person,setting.images(required) — 1–10 reference images. Each is either a publichttpsURL (≤ 10 MB each) or an inline base64 data URI (data:image/png;base64,…) —image/jpeg,image/png, orimage/webp. The whole MCP request is capped at 1 MB, so inline base64 images can carry only about 750 KB of file data in total — send larger images ashttpsURLs.instruction(optional) — the model’s always-applied guidance (≤ 8000 chars), injected as mandatory (“MUST FOLLOW”) direction into every generation that composes the model. See Model Training.webhook_url(optional) — anhttpsURL notified once when training reaches a terminal status.
{ id, status: "pending", estimated_credits }
immediately; poll get_job_status(kind="model", id=…) (which also needs the
models.read scope) until completed or failed, then use the model id in
generate_image / generate_video.
Free — model creation deducts no credits. Large-file presigned model uploads
are REST-only (not exposed over MCP) — use
POST /models/prepare for those. An
image_id from prepare_image_upload is not accepted here.update_model(model_id, …)
update_model(model_id, …)
model_id(required) — the model to update.name(optional) — a new model name.default_prompt(optional) — a new default prompt.instruction(optional) — the model’s always-applied guidance (≤ 8000 chars). Send an empty string to clear it.
name, default_prompt, or instruction; omitted
fields are left unchanged. Synchronous — returns the full updated model
immediately (same shape as get_model). Free.list_image_engines()
list_image_engines()
{ data: [...], unavailable_reason } — one entry per
text-to-image engine you can use, default first: id, name, is_default,
provider_family, aspect_ratios, default_aspect_ratio, resolutions,
default_resolution, max_num_outputs, credits_per_image (per resolution; a
request costs this × num_outputs), supports_trained_refs, and
supports_color_palette. The content is the same as
GET /images/models. Pass an entry’s
id as engine to generate_image.If your organization generates only with its trained models, data is empty
and unavailable_reason is organization_restricted; otherwise it is null.
Free. Scope images.generate.improve_prompt(prompt, target, …) — coming soon
improve_prompt(prompt, target, …) — coming soon
prompt(required) — the prompt to improve: 3–5000 characters after trimming, with the same rules as every Samsa prompt (no<or>, no backslashes, no line breaks or tabs).target(required) —imageorvideo: the medium the improved prompt is for.language(optional) — a BCP-47 language tag such asenordefor the language of the improved prompt. Omitted: the improved prompt keeps the language of your prompt.idempotency_key(optional) — 1–255 printable ASCII characters. The same key with the same arguments within 24 hours returns the stored result and is never charged twice; the same key with other arguments is rejected (idempotency_key_reused), and a key whose first call is still running returnsidempotency_in_progress. A key whose call failed returns that error again, so use a new key for a new paid attempt. Keys are scoped to the credential’s owner (the API key’s creator or the OAuth user) within the organization, and share one namespace with the RESTIdempotency-Keyheader.
{ improved_prompt, target, language, credits_charged } directly; there is no job to poll. Pass improved_prompt as
the prompt of generate_image or generate_video. Cost: 1 credit per
call, charged before the model runs; if the AI provider fails, the credit is
refunded and the tool returns a provider_error. Errors use the same structured
tool-error shape as the other tools. Scope: any one of
images.generate, images.edit, or videos.generate. REST equivalent:
POST /prompts/improve.generate_image(prompt, …)
generate_image(prompt, …)
prompt(required) — the text prompt.engine(optional) — the text-to-image model:nano_banana_pro(default),nano_banana_2_1,nano_banana_2,nano_banana,imagen_4,seedream_4, orflux_1_pro. Omit it to usenano_banana_pro. See Engines for each engine’s limits, or calllist_image_engines.style_id,object_ids,person_ids,setting_ids(optional) — trained model ids or names fromlist_modelsto compose (a name resolves to a model visible to you).color_palette(optional) — a color palette to apply, given as its name or id (same as the trained-model refs).num_outputs(1–4, default1),aspect_ratio(default"1:1"),resolution(default"1K").
aspect_ratio and resolution are validated against the engine:
nano_banana_pro, nano_banana_2_1, and nano_banana_2 accept 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 at 1K / 2K / 4K; nano_banana the first ten of those at 1K;
imagen_4 1:1, 16:9, 9:16, 4:3, 3:4 at 1K / 2K; seedream_4 and
flux_1_pro 1:1, 16:9, 9:16, 4:3, 3:4, 21:9 at 1K. An unknown
engine or an unsupported value returns a 422 naming the valid values.Trained models and color_palette work only with nano_banana_pro,
nano_banana_2_1, and nano_banana_2; on any other engine they return 422
— they are never dropped, and the engine is never switched. Some organizations
generate only with their trained models: there any engine returns 422 —
omit engine and pass at least one trained model or a color_palette.Async — returns { id, status: "pending", estimated_credits }
immediately. Cost: 5 × num_outputs × resolution (1K ×1, 2K ×2, 4K ×4),
deducted at submit — the same on every engine.edit_image(prompt, …)
edit_image(prompt, …)
prompt(required) — how to edit the image.- Exactly one of
image_id(an image in your Samsa context, for example fromcomplete_image_upload) orimage_url(a public https URL). The source aspect ratio is kept. engine(optional) —nano_banana_pro(Nano Banana Pro, default),nano_banana_2(Nano Banana 2),nano_banana_2_1(Nano Banana 2.1),gemini(Nano Banana via FAL), orkontext(Flux Kontext). An unknown engine returns422naming the valid values. See Engines and credits.resolution(optional) —1K(default),2K, or4Konnano_banana_pro,nano_banana_2, andnano_banana_2_1.geminiandkontexthave a fixed resolution: omitresolutionthere (a value returns422).num_images(optional) —1–4, default1.style_id,object_ids,person_ids,setting_ids(optional) — trained model ids or names fromlist_modelsto reuse for on-brand edits (a name resolves to a model visible to you), at parity withgenerate_image.color_palette(optional) — a color palette to apply, given as its name or id.
color_palette work only with nano_banana_pro (also when
you omit engine). Naming any other engine together with them returns 422
before any charge — the engine is never switched. Masked edits are REST-only
and run on nano_banana_pro or gemini.Async — returns { id, status: "pending", estimated_credits, engine, resolution }. engine and resolution are the effective values the edit
runs at (resolution is null on gemini and kontext). Cost per output: 5
credits × resolution on the three Nano Banana engines (1K 5, 2K 10, 4K
20), a fixed 5 on gemini and kontext; × num_images, deducted at submit.
For example, edit_image(prompt=…, image_id=…, resolution="4K") returns
estimated_credits: 20.img2img(prompt, images, …)
img2img(prompt, images, …)
prompt(required) — how to transform the sources.images(required) — 1–14 sources; each item is either{ image_id }or{ image_url }(an https URL). Source order is preserved. No base64 over MCP — see Image inputs.engine(optional) —nano_banana_pro(default),nano_banana_2, ornano_banana_2_1(Nano Banana 2.1).aspect_ratio(optional) — validated against the engine’s list (nano_banana_2andnano_banana_2_1additionally allow4:1,1:4,8:1,1:8); omitted preserves the source shape.resolution(1Kdefault,2K,4K),num_outputs(default1).
get_job_status(kind="img2img", id=…). Cost:
5 × num_outputs × resolution (1K ×1, 2K ×2, 4K ×4). Scope
images.edit.create_variations(image_id | image_url, …)
create_variations(image_id | image_url, …)
- One of
image_idorimage_url(required). target(optional) — what may change:everything(default),person,object,scene.creativity(optional) —subtleorcreative(default).variation_instructions/preservation_instructions(optional) — free text, ≤ 2000 chars each.num_outputs(1–4, default1).
resolution
argument). Async — poll get_job_status(kind="image_variation", id=…).
Cost: 5 × num_outputs × source resolution (1K ×1, 2K ×2, 4K ×4; a
source with no recoverable dimensions prices at 1K). Scope
images.transform.resize_image(aspect_ratio, image_id | image_url, …)
resize_image(aspect_ratio, image_id | image_url, …)
aspect_ratio(required) — one of21:9,16:9,3:2,4:3,5:4,1:1,4:5,3:4,2:3,9:16.- One of
image_idorimage_url(required). resolution(1Kdefault,2K,4K),num_outputs(1–4, default1).prompt(optional) — guidance for the newly exposed area.placement(optional) —{ gravity, scale }positioning the source on the canvas (gravityone ofcenter[default],top,bottom,left,right,top_left,top_right,bottom_left,bottom_right;scalein(0, 1]).
prompt is given, it returns
the flattened image and refunds the unused outputs. Async — poll
get_job_status(kind="image_resize", id=…). Cost: 5 × num_outputs × resolution. Scope images.transform.upscale_image(target_resolution, image_id | image_url, …)
upscale_image(target_resolution, image_id | image_url, …)
target_resolution(required) —2K,4K,6K,8K,10K,12K,14K,16K,20K,24K,28K,32K,38K(classes above16Karecrystal-only).- One of
image_idorimage_url(required). model(optional) —seedvr,crystal(default),magnific-creative,magnific-precision.options(optional) — per-model, strictly validated:options.magnific_creative(prompt,optimized_for,creativity/hdr/resemblance/fractalityin −10..10,engine) oroptions.magnific_precision(sharpen/smart_grain/ultra_detailin 0..100,flavor).seedvr/crystaltake no options.
get_job_status(kind="image_upscale", id=…). Cost: the resolution tier ×
the model multiplier (Magnific ×3); crystal above 12K prices by output
megapixels — see pricing. Scope images.transform.remove_background(image_id | image_url)
remove_background(image_id | image_url)
- One of
image_idorimage_url(required).
get_job_status(kind="image_background_removal", id=…). Cost: 1 credit on
a miss; 0 on a cache hit — an owned image_id that already has a
background-removed result returns { status: "completed", estimated_credits: 0 }
right away. Scope images.transform.vectorize_image(svg_acceptance, image_id | image_url)
vectorize_image(svg_acceptance, image_id | image_url)
svg_acceptance(required) — must be the literal booleantrue.- One of
image_idorimage_url(required). engine(optional, defaultrecraft) —recraftorideogram.mode(optional) —default(detailed, the default) orsimple. Valid only withengine: "ideogram"; any other combination is rejected422with no charge.
422 svg_acceptance_required and nothing is
charged. Delivery also requires your organization to have accepted the current
ToS/AUP (verified server-side); if not, the call is rejected
403 svg_phase1_scope_out_required with no charge. Async — poll
get_job_status(kind="image_vectorize", id=…). Cost: 5 on a miss (every
engine and mode); 0 on a cache hit — a cached result counts only when it
comes from the same engine and mode. Scope images.transform.generate_video(mode, …)
generate_video(mode, …)
mode(required) — one of:image_to_video— animate a start frame. Requires exactly one ofimage_id/image_url; optionalend_image_urlon end-frame-capable engines;promptoptional.text_to_video— requiresprompt.text_to_video_styled— requirespromptandstyle_id;object_ids/person_ids/setting_idsoptional, plus an optionalcolor_palette(name or id).
engine(defaultveo_3_1_lite),duration(default: the engine’s shortest supported duration, in seconds),aspect_ratio(default"16:9"; also9:16,1:1).- Kling 4.0 (
engine: "kling_4_0") —durationis any whole second from3to30, default5. The tool has noresolutionparameter, so the video is720p, with a soundtrack that is always on: 15 credits per second (a 5 s clip is75). Onimage_to_videothe video follows the framing of the start image. See Kling 4.0.
{ id, status: "pending", estimated_credits }. Cost:
5 / second × engine × resolution × audio multipliers; styled mode adds a
flat 10 for the intermediate image. See pricing.get_job_status(kind, id)
get_job_status(kind, id)
kind(required) — one ofimage_generation,image_edit,img2img,image_variation,image_resize,image_upscale,image_background_removal,image_vectorize,video, ormodel. Use the kind the submitting tool told you to poll.id(required) — the job or model id a submit tool returned.
pending → processing → completed / failed) and,
once completed, presigned result URLs valid for 24 hours. Requires the scope
of the submitting tool (models.read for kind: "model").processing means “poll again”. For the image kinds image_generation,
image_edit, img2img, image_variation, and image_resize:- When all outputs failed the compliance pipeline (for example C2PA
signing), the job is
failedwitherrorset todelivery_blocked_compliance: <codes>and no images. This is terminal — stop polling. - When only some outputs failed it, the job is
completed:imagesholds the deliverable outputs andblocked_imageslists the others as{ id, reason }.reasoniscompliance_failed_signing,compliance_failed_storage,compliance_failed_watermark, ormissing_provenance_state.
image_vectorize — the response also includes a downscaled inline preview,
so MCP clients can render it directly, alongside the link to the
full-resolution asset. image_vectorize returns an SVG (no raster preview): use
the presigned URL. The preview is a reduced-resolution copy for quick display;
fetch the link for the original.get_credit_balance()
get_credit_balance()
available and
spendable_plan_credits) alongside the organization-wide plan_credits and
topup_credits, the current billing period, and scope — the budget regime the
connection draws from. available can be lower than plan_credits when the
organization reserves plan credits for teams, which is why a job can be refused for
insufficient credits while the organization still shows a balance. See
GET /credits for the full field semantics.prepare_image_upload(filename, content_type, size_bytes, …)
prepare_image_upload(filename, content_type, size_bytes, …)
-
Call
prepare_image_uploadwith:filename(required) — the file name.content_type(required) —image/jpeg,image/png, orimage/webp.size_bytes(required) — the file’s exact size in bytes (for example fromwc -c < photo.png). It is signed into the URL, so aPUTof any other length is rejected.width,height(optional) — used only to refuse an image over 32 MP early.
{ image_id, upload_url, expires_at, max_bytes, allowed_content_types }and anext_stepstring. -
PUTthe raw file bytes toupload_urlyourself, outside MCP, with the sameContent-Typeand noAuthorizationheader: -
Call
complete_image_upload(image_id)within the hour.
upload_url
expires after 1 hour; at most 20 uploads awaiting completion per user
(too_many_pending_uploads above that). The image belongs to the calling user
(the API key’s creator or the OAuth user) — other members of your organization
cannot use it. Free. Scope: any one of images.edit, images.transform, or
videos.generate. REST equivalent:
Image Uploads.complete_image_upload(image_id)
complete_image_upload(image_id)
image_id(required) — the idprepare_image_uploadreturned.
PUT. Verifies the stored file (present, exactly
size_bytes, at most 10 MB, a readable image of the prepared content_type, at
most 32 megapixels) and returns { image_id, status: "completed", filename, content_type, size_bytes, width, height }. Synchronous — the image_id is
usable right away as the source of edit_image, img2img, upscale_image,
resize_image, create_variations, remove_background, vectorize_image, and
generate_video (mode: "image_to_video"). Before this call succeeds, the
image_id is not usable anywhere.Safe to call again: it returns the same result, and a later PUT does not
change the completed image. A file that fails a check returns a validation
error and is discarded — PUT a valid file to the same upload_url while it is
still valid and call this again. An unknown, expired, or another user’s
image_id returns not_found; upload_in_progress means another call is
completing it right now — call again in a few seconds. Free. Same scopes as
prepare_image_upload.