> ## 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 > Jedes Tool des Samsa MCP servers — mit Parametern, benötigtem Scope und Credit-Preis. Der Server stellt **fünfzehn Tools** bereit. Sechs sind kostenlos — die vier Reads (`list_models`, `get_model`, `get_job_status`, `get_credit_balance`) und die beiden Modell-Verwaltungs-Tools (`create_model`, `update_model`). Die anderen **neun** kosten [Credits](/de/guides/pricing) aus dem Pool deiner Organisation, zu denselben Raten wie App und REST API. | Tool | Was es tut | Scope | Kosten | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------- | | `list_models` | Listet die einsatzbereiten trainierten Modelle deiner Organisation (id, name, category, thumbnail). | `models.read` | Kostenlos | | `get_model` | Vollständige Details zu einem Modell — status, Referenzbilder, Default-Prompt, Trigger-Wörter. | `models.read` | Kostenlos | | `create_model` | Trainiert ein neues Modell aus 1–10 Referenzbildern (async). | `models.write` | Kostenlos | | `update_model` | Aktualisiert Name, Default-Prompt und/oder die stets angewandte Instruction eines Modells. | `models.write` | Kostenlos | | `generate_image` | Generiert Bilder aus einem Prompt und komponiert dabei optional deine trainierten Modelle. | `images.generate` | 5 × outputs × Auflösung | | `edit_image` | Magic Edit — bearbeitet ein Bild per Prompt. | `images.edit` | 5 pro output | | `img2img` | Transformiert 1–14 Referenzbilder per Prompt. | `images.edit` | 5 × outputs × Auflösung | | `create_variations` | Generiert kreative Variationen eines Bilds. | `images.transform` | 5 × outputs × Quellauflösung | | `resize_image` | Ändert das Seitenverhältnis per Outpainting. | `images.transform` | 5 × outputs × Auflösung | | `upscale_image` | Upscalt ein Bild auf eine höhere Auflösung (vier Modelle). | `images.transform` | Stufe × Modell-Multiplikator | | `remove_background` | Entfernt den Hintergrund (transparentes PNG). | `images.transform` | 1 (0 bei einem Cache-Treffer) | | `vectorize_image` | Vektorisiert ein Bild zu SVG. | `images.transform` | 5 (0 bei einem Cache-Treffer) | | `generate_video` | Generiert Video aus einem Startframe, aus Text oder aus Text, der mit deinen Modellen gestylt ist. | `videos.generate` | 5 / Sekunde × Engine × Auflösung × Audio | | `get_job_status` | Fragt einen eingereichten Bild-, Transform-, Video- oder Modell-Job nach Status und Ergebnissen ab. | Scope des einreichenden Tools | Kostenlos | | `get_credit_balance` | Liest den Credit-Stand, den diese Verbindung ausgeben kann, die organisationsweiten Summen, ihren Budget-Scope und den Abrechnungszeitraum. | `usage.read` | Kostenlos | Ein Tool-Aufruf, der wegen eines fehlenden Scopes abgelehnt wird, gibt einen strukturierten Tool-Fehler zurück (keinen Crash) und nennt den benötigten Scope. Keys werden standardmäßig mit allen Scopes erstellt; ein Admin kann einen Key in **Settings → API Keys** einschränken oder erweitern. ## Parameter * `category` *(optional)* — filtert auf eines von `style`, `object`, `person`, `setting`. Gibt die **einsatzbereiten** Modelle deiner Organisation mit `id`, `name`, `category` und einer presigned `thumbnail_url` zurück. Verwende die ids oder Namen als `style_id` / `object_ids` / `person_ids` / `setting_ids` in `generate_image` und `generate_video` — ein Name wird zu einem für dich sichtbaren Modell aufgelöst. * `model_id` *(erforderlich)* — die id des Modells. Gibt vollständige Details zurück: status, Einsatzbereitschaft, presigned URLs der Referenzbilder, den Default-Prompt und Trigger-Wörter. * `name` *(erforderlich)* — der Modellname. * `category` *(erforderlich)* — eines von `style`, `object`, `person`, `setting`. * `images` *(erforderlich)* — 1–10 Referenzbilder. Jedes ist **entweder** eine öffentliche `https`-URL **oder** ein inline base64-Data-URI (`data:image/png;base64,…`) — `image/jpeg`, `image/png` oder `image/webp`, je ≤ 10 MB. * `instruction` *(optional)* — die stets angewandte Guidance des Modells (≤ 8000 Zeichen), die als verbindliche ("MUST FOLLOW") Vorgabe in jede Generierung eingespeist wird, die das Modell komponiert. Siehe [Modelltraining](/de/api-reference/model-training/overview). * `webhook_url` *(optional)* — eine `https`-URL, die einmal benachrichtigt wird, sobald das Training einen finalen Status erreicht. **Async** — gibt sofort `{ id, status: "pending", estimated_credits }` zurück; frage `get_job_status(kind="model", id=…)` ab (das zusätzlich den `models.read` Scope erfordert), bis `completed` oder `failed`, und verwende die Modell-id dann in `generate_image` / `generate_video`. **Kostenlos** — die Modellerstellung zieht keine Credits ab. Presigned Uploads großer Dateien sind REST-only (nicht über MCP verfügbar) — nutze dafür [`POST /models/prepare`](/de/api-reference/model-training/prepare). * `model_id` *(erforderlich)* — das zu aktualisierende Modell. * `name` *(optional)* — ein neuer Modellname. * `default_prompt` *(optional)* — ein neuer Default-Prompt. * `instruction` *(optional)* — die stets angewandte Guidance des Modells (≤ 8000 Zeichen). Sende einen leeren String, um sie zu löschen. Gib **mindestens eines** von `name`, `default_prompt` oder `instruction` an; ausgelassene Felder bleiben unverändert. **Synchron** — gibt sofort das vollständige aktualisierte Modell zurück (gleiche Form wie `get_model`). **Kostenlos.** * `prompt` *(erforderlich)* — der Text-Prompt. * `style_id`, `object_ids`, `person_ids`, `setting_ids` *(optional)* — ids oder Namen trainierter Modelle aus `list_models` zum Komponieren (ein Name wird zu einem für dich sichtbaren Modell aufgelöst). * `color_palette` *(optional)* — eine anzuwendende Farbpalette, angegeben als **Name oder id** (wie bei den Referenzen auf trainierte Modelle). * `num_outputs` (`1`–`4`, Default `1`), `aspect_ratio` (Default `"1:1"`), `resolution` (Default `"1K"`; `1K` / `2K` / `4K`). `aspect_ratio` akzeptiert `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` und `8:1`. **Async** — gibt sofort `{ id, status: "pending", estimated_credits }` zurück. Kosten: `5 × num_outputs × Auflösung` (`1K` ×1, `2K` ×2, `4K` ×4), abgezogen beim Einreichen. * `prompt` *(erforderlich)* — wie das Bild bearbeitet werden soll. * Genau **eines** von `image_id` (ein Bild in deinem Samsa-Kontext) oder `image_url` (eine öffentliche https-URL). * `style_id`, `object_ids`, `person_ids`, `setting_ids` *(optional)* — ids oder Namen trainierter Modelle aus `list_models`, um sie für markenkonforme Edits wiederzuverwenden (ein Name wird zu einem für dich sichtbaren Modell aufgelöst), gleichauf mit `generate_image`. * `color_palette` *(optional)* — eine anzuwendende Farbpalette, angegeben als **Name oder id**. * `engine` *(optional)* — `nano_banana_pro` (Default), `gemini` oder `kontext`. Die Angabe einer trainierten-Modell-Referenz oder einer Farbpalette erzwingt `nano_banana_pro`. **Async** — gibt `{ id, status: "pending", estimated_credits }` zurück. Kosten: 5 Credits pro output (`nano_banana_pro` skaliert mit der Auflösung: `1K` ×1, `2K` ×2, `4K` ×4), abgezogen beim Einreichen. * `prompt` *(erforderlich)* — wie die Quellen transformiert werden sollen. * `images` *(erforderlich)* — **1–14** Quellen; jedes Element ist **entweder** `{ image_id }` **oder** `{ image_url }` (eine https-URL). Die Quellreihenfolge bleibt erhalten. Kein base64 über MCP — siehe [Bild-Eingaben](/de/guides/image-inputs). * `engine` *(optional)* — `nano_banana_pro` (Default) oder `nano_banana_2`. * `aspect_ratio` *(optional)* — gegen die Liste der Engine validiert (`nano_banana_2` erlaubt zusätzlich `4:1`, `1:4`, `8:1`, `1:8`); ausgelassen bleibt die Quellform erhalten. * `resolution` (`1K` Default, `2K`, `4K`), `num_outputs` (Default `1`). **Async** — frage `get_job_status(kind="img2img", id=…)` ab. Kosten: `5 × num_outputs × Auflösung` (`1K` ×1, `2K` ×2, `4K` ×4). Scope `images.edit`. * **Eines** von `image_id` oder `image_url` *(erforderlich)*. * `target` *(optional)* — was sich ändern darf: `everything` (Default), `person`, `object`, `scene`. * `creativity` *(optional)* — `subtle` oder `creative` (Default). * `variation_instructions` / `preservation_instructions` *(optional)* — Freitext, je ≤ 2000 Zeichen. * `num_outputs` (`1`–`4`, Default `1`). Die Ausgabe-**Auflösung wird von der Quelle geerbt** (kein `resolution`-Argument). **Async** — frage `get_job_status(kind="image_variation", id=…)` ab. Kosten: `5 × num_outputs × Quellauflösung` (`1K` ×1, `2K` ×2, `4K` ×4; eine Quelle ohne ermittelbare Abmessungen wird mit `1K` berechnet). Scope `images.transform`. * `aspect_ratio` *(erforderlich)* — eines von `21:9`, `16:9`, `3:2`, `4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `2:3`, `9:16`. * **Eines** von `image_id` oder `image_url` *(erforderlich)*. * `resolution` (`1K` Default, `2K`, `4K`), `num_outputs` (`1`–`4`, Default `1`). * `prompt` *(optional)* — Vorgabe für den neu freigelegten Bereich. * `placement` *(optional)* — `{ gravity, scale }`, das die Quelle auf der Leinwand positioniert (`gravity` eines von `center` \[Default], `top`, `bottom`, `left`, `right`, `top_left`, `top_right`, `bottom_left`, `bottom_right`; `scale` in `(0, 1]`). Ändert die Größe per Outpainting — der Server füllt die neue Leinwand mit einer stilangepassten Erweiterung. Wenn nichts Neues zu generieren ist und kein `prompt` angegeben wird, gibt er das zusammengeführte Bild zurück und erstattet die ungenutzten outputs. **Async** — frage `get_job_status(kind="image_resize", id=…)` ab. Kosten: `5 × num_outputs × Auflösung`. Scope `images.transform`. * `target_resolution` *(erforderlich)* — `2K`, `4K`, `6K`, `8K`, `10K`, `12K`, `14K`, `16K`, `20K`, `24K`, `28K`, `32K`, `38K` (Klassen über `16K` sind **nur mit `crystal`**). * **Eines** von `image_id` oder `image_url` *(erforderlich)*. * `model` *(optional)* — `seedvr`, `crystal` (Default), `magnific-creative`, `magnific-precision`. * `options` *(optional)* — pro Modell, streng validiert: `options.magnific_creative` (`prompt`, `optimized_for`, `creativity`/`hdr`/`resemblance`/`fractality` in −10..10, `engine`) oder `options.magnific_precision` (`sharpen`/`smart_grain`/`ultra_detail` in 0..100, `flavor`). `seedvr`/`crystal` nehmen keine Optionen. Die modellspezifischen Faktor-/Flächengrenzen werden **vor** der Belastung validiert. **Async** — frage `get_job_status(kind="image_upscale", id=…)` ab. Kosten: die Auflösungsstufe × den Modell-Multiplikator (Magnific ×3); `crystal` über `12K` wird nach Ausgabe-Megapixeln berechnet — siehe [Preise](/de/guides/pricing#upscale). Scope `images.transform`. * **Eines** von `image_id` oder `image_url` *(erforderlich)*. Erzeugt ein transparentes PNG; es gibt keinen Modell-Parameter. **Async** — frage `get_job_status(kind="image_background_removal", id=…)` ab. Kosten: **1** Credit bei einem Miss; **0** bei einem Cache-Treffer — eine dir gehörende `image_id`, die bereits ein Ergebnis der Hintergrundentfernung hat, gibt sofort `{ status: "completed", estimated_credits: 0 }` zurück. Scope `images.transform`. * `svg_acceptance` *(erforderlich)* — muss der literale Boolean `true` sein. * **Eines** von `image_id` oder `image_url` *(erforderlich)*. Erzeugt ein **SVG**. Ein SVG kann kein C2PA-Manifest oder Wasserzeichen tragen, daher wird die Vektorausgabe ohne Signatur ausgeliefert — siehe [Content-Provenienz](/de/guides/content-provenance). Die Bestätigung ist Offenlegungs-/Prüfnachweis, kein Compliance-Verzicht; ohne sie wird der Aufruf mit `422 svg_acceptance_required` abgelehnt und nichts berechnet. Die Auslieferung erfordert außerdem, dass deine Organisation die aktuellen ToS/AUP akzeptiert hat (serverseitig verifiziert); andernfalls wird der Aufruf mit `403 svg_phase1_scope_out_required` ohne Belastung abgelehnt. **Async** — frage `get_job_status(kind="image_vectorize", id=…)` ab. Kosten: **5** bei einem Miss; **0** bei einem Cache-Treffer. Scope `images.transform`. * `mode` *(erforderlich)* — eines von: * `image_to_video` — animiert einen Startframe. Erfordert genau eines von `image_id` / `image_url`; optional `end_image_url` bei endframe-fähigen Engines; `prompt` optional. * `text_to_video` — erfordert `prompt`. * `text_to_video_styled` — erfordert `prompt` **und** `style_id`; `object_ids` / `person_ids` / `setting_ids` optional, plus eine optionale `color_palette` (Name oder id). * `engine` *(Default `veo_3_1_lite`)*, `duration` *(Default: die kürzeste von der Engine unterstützte Dauer, in Sekunden)*, `aspect_ratio` *(Default `"16:9"`; auch `9:16`, `1:1`)*. **Async** — gibt `{ id, status: "pending", estimated_credits }` zurück. Kosten: `5 / Sekunde × Engine × Auflösung × Audio`-Multiplikatoren; der styled-Modus addiert pauschal 10 für das Zwischenbild. Siehe [Preise](/de/guides/pricing#videogenerierung). * `kind` *(erforderlich)* — eines von `image_generation`, `image_edit`, `img2img`, `image_variation`, `image_resize`, `image_upscale`, `image_background_removal`, `image_vectorize`, `video` oder `model`. Verwende den kind, den dir das einreichende Tool zum Abfragen genannt hat. * `id` *(erforderlich)* — die Job- oder Modell-id, die ein Submit-Tool zurückgegeben hat. Gibt den Status (`pending` → `processing` → `completed` / `failed`) zurück und, sobald `completed`, presigned Ergebnis-URLs, die 24 Stunden gültig sind. Erfordert den Scope des einreichenden Tools (`models.read` für `kind: "model"`). Bei einem abgeschlossenen **Raster-Bild**-Job — jeder Bild-kind **außer** `image_vectorize` — enthält die Antwort außerdem eine **herunterskalierte Inline-Vorschau**, sodass MCP clients sie direkt rendern können, neben dem Link zum Asset in voller Auflösung. `image_vectorize` gibt ein SVG zurück (keine Raster-Vorschau): nutze die presigned URL. Die Vorschau ist eine Kopie mit reduzierter Auflösung für die schnelle Anzeige; rufe den Link für das Original ab. Keine Parameter. Gibt zurück, was **diese Verbindung** ausgeben kann (`available` und `spendable_plan_credits`), zusammen mit den organisationsweiten `plan_credits` und `topup_credits`, dem aktuellen Abrechnungszeitraum und `scope` — dem Budget-Regime, aus dem die Verbindung ausgibt. `available` kann niedriger sein als `plan_credits`, wenn die Organisation Plan-Credits für Teams reserviert; deshalb kann ein Job wegen fehlender Credits abgelehnt werden, während die Organisation noch ein Guthaben ausweist. Die vollständige Feldsemantik steht unter [`GET /credits`](/de/api-reference/account/credits).