> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP tools
> Every tool the Samsa MCP server exposes, with its parameters, required scope, and credit cost.
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](/guides/pricing) from your organization's pool, at the same rates as the
app and REST API.
| Tool | What it does | Scope | Cost |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------------------- |
| `list_models` | List your organization's ready trained models (id, name, category, thumbnail). | `models.read` | Free |
| `get_model` | Full detail for one model — status, reference images, default prompt, trigger words. | `models.read` | Free |
| `create_model` | Train a new model from 1–10 reference images (async). | `models.write` | Free |
| `update_model` | Update a model's name, default prompt, and/or always-applied instruction. | `models.write` | Free |
| `generate_image` | Generate images from a prompt, optionally composing your trained models. | `images.generate` | 5 × outputs × resolution |
| `edit_image` | Magic Edit — edit an image from a prompt. | `images.edit` | 5 per output |
| `img2img` | Transform 1–14 reference images with a prompt. | `images.edit` | 5 × outputs × resolution |
| `create_variations` | Generate creative variations of one image. | `images.transform` | 5 × outputs × source resolution |
| `resize_image` | Resize to a new aspect ratio by outpainting. | `images.transform` | 5 × outputs × resolution |
| `upscale_image` | Upscale one image to a higher resolution (four models). | `images.transform` | Tier × model multiplier |
| `remove_background` | Remove the background (transparent PNG). | `images.transform` | 1 (0 on a cache hit) |
| `vectorize_image` | Vectorize one image to SVG. | `images.transform` | 5 (0 on a cache hit) |
| `generate_video` | Generate video from a start frame, from text, or from text styled with your models. | `videos.generate` | 5 / second × engine × resolution × audio |
| `get_job_status` | Poll a submitted image, transform, video, or model job for status and results. | scope of the submitting tool | Free |
| `get_credit_balance` | Read the credit balance this connection can spend, the organization-wide totals, its budget scope, and the billing period. | `usage.read` | Free |
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](/api-reference/model-training/overview).
* `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`](/api-reference/model-training/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](/guides/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](/guides/pricing#upscale). 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](/guides/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](/guides/pricing#video-generation).
* `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`](/api-reference/account/credits) for the full field semantics.