Skip to main content
The server exposes eighteen tools. Nine are free — the five reads (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.
Coming soon: 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.
A tool call rejected for a missing scope returns a structured tool error (not a crash) naming the scope it needs. Keys are created with all scopes by default; an admin can narrow or widen a key in Settings → API Keys.

Parameters

  • category (optional) — filter to one of style, object, person, setting.
Returns your organization’s ready models with 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.
  • model_id (required) — the model’s id.
Returns full detail: status, readiness, presigned reference-image URLs, the default prompt, and trigger words.
  • name (required) — the model name.
  • category (required) — one of style, object, person, setting.
  • images (required) — 1–10 reference images. Each is either a public https URL (≤ 10 MB each) or an inline base64 data URI (data:image/png;base64,…) — image/jpeg, image/png, or image/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 as https URLs.
  • 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) — an https URL notified once when training reaches a terminal status.
Async — returns { 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.
  • 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.
Supply at least one of name, default_prompt, or instruction; omitted fields are left unchanged. Synchronous — returns the full updated model immediately (same shape as get_model). Free.
No parameters. Returns { 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.
Coming soon — not in the server’s tool list until prompt improvement is enabled.
  • 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) — image or video: the medium the improved prompt is for.
  • language (optional) — a BCP-47 language tag such as en or de for 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 returns idempotency_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 REST Idempotency-Key header.
Synchronous — returns { 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.
  • 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, or flux_1_pro. Omit it to use nano_banana_pro. See Engines for each engine’s limits, or call list_image_engines.
  • style_id, object_ids, person_ids, setting_ids (optional) — trained model ids or names from list_models to 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, default 1), 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.
  • prompt (required) — how to edit the image.
  • Exactly one of image_id (an image in your Samsa context, for example from complete_image_upload) or image_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), or kontext (Flux Kontext). An unknown engine returns 422 naming the valid values. See Engines and credits.
  • resolution (optional) — 1K (default), 2K, or 4K on nano_banana_pro, nano_banana_2, and nano_banana_2_1. gemini and kontext have a fixed resolution: omit resolution there (a value returns 422).
  • num_images (optional) — 1–4, default 1.
  • style_id, object_ids, person_ids, setting_ids (optional) — trained model ids or names from list_models to reuse for on-brand edits (a name resolves to a model visible to you), at parity with generate_image.
  • color_palette (optional) — a color palette to apply, given as its name or id.
Trained models and 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.
  • 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, or nano_banana_2_1 (Nano Banana 2.1).
  • aspect_ratio (optional) — validated against the engine’s list (nano_banana_2 and nano_banana_2_1 additionally allow 4:1, 1:4, 8:1, 1:8); omitted preserves the source shape.
  • resolution (1K default, 2K, 4K), num_outputs (default 1).
Async — poll get_job_status(kind="img2img", id=…). Cost: 5 × num_outputs × resolution (1K ×1, 2K ×2, 4K ×4). Scope images.edit.
  • One of image_id or image_url (required).
  • target (optional) — what may change: everything (default), person, object, scene.
  • creativity (optional) — subtle or creative (default).
  • variation_instructions / preservation_instructions (optional) — free text, ≤ 2000 chars each.
  • num_outputs (1–4, default 1).
The output resolution is inherited from the source (no 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.
  • aspect_ratio (required) — one of 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16.
  • One of image_id or image_url (required).
  • resolution (1K default, 2K, 4K), num_outputs (1–4, default 1).
  • prompt (optional) — guidance for the newly exposed area.
  • placement (optional) — { gravity, scale } positioning the source on the canvas (gravity one of center [default], top, bottom, left, right, top_left, top_right, bottom_left, bottom_right; scale in (0, 1]).
Resizes by outpainting — the server fills the new canvas with a style-matched extension. If nothing new needs generating and no 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.
  • target_resolution (required) — 2K, 4K, 6K, 8K, 10K, 12K, 14K, 16K, 20K, 24K, 28K, 32K, 38K (classes above 16K are crystal-only).
  • One of image_id or image_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/fractality in −10..10, engine) or options.magnific_precision (sharpen/smart_grain/ultra_detail in 0..100, flavor). seedvr/crystal take no options.
Per-model factor/area caps are validated before charging. Async — poll 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.
  • One of image_id or image_url (required).
Produces a transparent PNG; there is no model parameter. Async — poll 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.
  • svg_acceptance (required) — must be the literal boolean true.
  • One of image_id or image_url (required).
  • engine (optional, default recraft) — recraft or ideogram.
  • mode (optional) — default (detailed, the default) or simple. Valid only with engine: "ideogram"; any other combination is rejected 422 with no charge.
Produces an SVG. An SVG cannot carry a C2PA manifest or watermark, so vector output is delivered unsigned — see Content provenance. The acknowledgment is disclosure / audit evidence, not a compliance waiver; without it the call is rejected 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.
  • mode (required) — one of:
    • image_to_video — animate a start frame. Requires exactly one of image_id / image_url; optional end_image_url on end-frame-capable engines; prompt optional.
    • text_to_video — requires prompt.
    • text_to_video_styled — requires prompt and style_id; object_ids / person_ids / setting_ids optional, plus an optional color_palette (name or id).
  • engine (default veo_3_1_lite), duration (default: the engine’s shortest supported duration, in seconds), aspect_ratio (default "16:9"; also 9:16, 1:1).
  • Kling 4.0 (engine: "kling_4_0") — duration is any whole second from 3 to 30, default 5. The tool has no resolution parameter, so the video is 720p, with a soundtrack that is always on: 15 credits per second (a 5 s clip is 75). On image_to_video the video follows the framing of the start image. See Kling 4.0.
Async — returns { id, status: "pending", estimated_credits }. Cost: 5 / second × engine × resolution × audio multipliers; styled mode adds a flat 10 for the intermediate image. See pricing.
  • kind (required) — one of image_generation, image_edit, img2img, image_variation, image_resize, image_upscale, image_background_removal, image_vectorize, video, or model. Use the kind the submitting tool told you to poll.
  • id (required) — the job or model id a submit tool returned.
Returns the status (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 failed with error set to delivery_blocked_compliance: <codes> and no images. This is terminal — stop polling.
  • When only some outputs failed it, the job is completed: images holds the deliverable outputs and blocked_images lists the others as { id, reason }. reason is compliance_failed_signing, compliance_failed_storage, compliance_failed_watermark, or missing_provenance_state.
For a completed raster image job — every image kind except 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.
No parameters. Returns what this connection can spend (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.
MCP tool arguments cannot carry file bytes. To use a local image file as a source, upload it in three steps:
  1. Call prepare_image_upload with:
    • filename (required) — the file name.
    • content_type (required) — image/jpeg, image/png, or image/webp.
    • size_bytes (required) — the file’s exact size in bytes (for example from wc -c < photo.png). It is signed into the URL, so a PUT of any other length is rejected.
    • width, height (optional) — used only to refuse an image over 32 MP early.
    It returns { image_id, upload_url, expires_at, max_bytes, allowed_content_types } and a next_step string.
  2. PUT the raw file bytes to upload_url yourself, outside MCP, with the same Content-Type and no Authorization header:
  3. Call complete_image_upload(image_id) within the hour.
Limits: at most 10 MB (10,485,760 bytes) and 32 megapixels; 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.
  • image_id (required) — the id prepare_image_upload returned.
Call it after the 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.