Skip to main content
The server exposes fifteen tools. Six are free — the four reads (list_models, get_model, get_job_status, get_credit_balance) and the two model-management tools (create_model, update_model). The other nine cost credits from your organization’s pool, at the same rates as the app and REST API.
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.
  • 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 or an inline base64 data URI (data:image/png;base64,…) — image/jpeg, image/png, or image/webp, ≤ 10 MB each.
  • 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 uploads are REST-only (not exposed over MCP) — use POST /models/prepare for those.
  • 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.
  • prompt (required) — the text prompt.
  • 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"; 1K / 2K / 4K).
aspect_ratio accepts 1:1 (default), 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, and 8:1.Async — returns { id, status: "pending", estimated_credits } immediately. Cost: 5 × num_outputs × resolution (1K ×1, 2K ×2, 4K ×4), deducted at submit.
  • prompt (required) — how to edit the image.
  • Exactly one of image_id (an image in your Samsa context) or image_url (a public https URL).
  • 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.
  • engine (optional) — nano_banana_pro (default), gemini, or kontext. Supplying any trained-model ref or a color palette forces nano_banana_pro.
Async — returns { id, status: "pending", estimated_credits }. Cost: 5 credits per output (nano_banana_pro scales with resolution: 1K ×1, 2K ×2, 4K ×4), deducted at submit.
  • 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) or nano_banana_2.
  • aspect_ratio (optional) — validated against the engine’s list (nano_banana_2 additionally allows 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).
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; 0 on a cache hit. 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).
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").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.