Zum Hauptinhalt springen
Der Server stellt achtzehn Tools bereit. Neun sind kostenlos — die fünf Reads (list_models, get_model, list_image_engines, get_job_status, get_credit_balance), die beiden Modell-Verwaltungs-Tools (create_model, update_model) und die beiden Upload-Tools (prepare_image_upload, complete_image_upload). Die anderen neun kosten Credits aus dem Pool deiner Organisation, zu denselben Raten wie App und REST API.
Demnächst verfügbar: improve_prompt, ein neunzehntes Tool, das 1 Credit pro Aufruf kostet. Es ist noch nicht in der Tool-Liste des Servers; es erscheint dort, sobald die Prompt-Verbesserung aktiviert ist. Seine Zeile und sein Abschnitt unten beschreiben es ab dem Start.
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. Die allgemeinen Text-to-Image-Engines sind keine trainierten Modelle — list_image_engines listet sie.
  • 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 (je ≤ 10 MB) oder ein inline base64-Data-URI (data:image/png;base64,…) — image/jpeg, image/png oder image/webp. Der gesamte MCP-Request ist auf 1 MB begrenzt, daher können inline base64-Bilder insgesamt nur etwa 750 KB Dateidaten tragen — sende größere Bilder als https-URLs.
  • 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.
  • 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 Modell-Uploads großer Dateien sind REST-only (nicht über MCP verfügbar) — nutze dafür POST /models/prepare. Eine image_id aus prepare_image_upload wird hier nicht akzeptiert.
  • 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.
Keine Parameter. Gibt { data: [...], unavailable_reason } zurück — ein Eintrag pro Text-to-Image-Engine, die du nutzen kannst, die Standard-Engine zuerst: id, name, is_default, provider_family, aspect_ratios, default_aspect_ratio, resolutions, default_resolution, max_num_outputs, credits_per_image (pro Auflösung; eine Anfrage kostet diesen Wert × num_outputs), supports_trained_refs und supports_color_palette. Der Inhalt ist derselbe wie bei GET /images/models. Übergib die id eines Eintrags als engine an generate_image.Generiert deine Organisation nur mit ihren trainierten Modellen, ist data leer und unavailable_reason ist organization_restricted; sonst ist es null. Kostenlos. Scope images.generate.
Demnächst verfügbar — nicht in der Tool-Liste des Servers, bis die Prompt-Verbesserung aktiviert ist.
  • prompt (erforderlich) — der zu verbessernde Prompt: 3–5000 Zeichen nach dem Trimmen, mit denselben Regeln wie für jeden Samsa-Prompt (kein < oder >, keine Backslashes, keine Zeilenumbrüche oder Tabs).
  • target (erforderlich) — image oder video: das Medium, für das der verbesserte Prompt gedacht ist.
  • language (optional) — ein BCP-47-Sprach-Tag wie en oder de für die Sprache des verbesserten Prompts. Weggelassen: Der verbesserte Prompt behält die Sprache deines Prompts.
  • idempotency_key (optional) — 1–255 druckbare ASCII-Zeichen. Derselbe Key mit denselben Argumenten innerhalb von 24 Stunden gibt das gespeicherte Ergebnis zurück und wird nie doppelt berechnet; derselbe Key mit anderen Argumenten wird abgelehnt (idempotency_key_reused), und ein Key, dessen erster Aufruf noch läuft, gibt idempotency_in_progress zurück. Ein Key, dessen Aufruf fehlgeschlagen ist, gibt diesen Fehler erneut zurück — verwende für einen neuen bezahlten Versuch einen neuen Key. Keys gelten pro Inhaber der Zugangsdaten (Ersteller des API-Keys oder OAuth-User) innerhalb der Organisation und teilen sich einen Namensraum mit dem REST-Header Idempotency-Key.
Synchron — gibt { improved_prompt, target, language, credits_charged } direkt zurück; es gibt keinen Job zum Abfragen. Gib improved_prompt als prompt an generate_image oder generate_video weiter. Kosten: 1 Credit pro Aufruf, abgebucht bevor das Modell läuft; schlägt der KI-Provider fehl, wird der Credit erstattet und das Tool gibt einen provider_error zurück. Fehler haben dieselbe strukturierte Tool-Fehler-Form wie bei den anderen Tools. Scope: einer von images.generate, images.edit oder videos.generate. REST-Entsprechung: POST /prompts/improve.
  • prompt (erforderlich) — der Text-Prompt.
  • engine (optional) — das Text-to-Image-Modell: nano_banana_pro (Default), nano_banana_2_1, nano_banana_2, nano_banana, imagen_4, seedream_4 oder flux_1_pro. Lass es weg, um nano_banana_pro zu nutzen. Die Limits jeder Engine stehen unter Engines, oder rufe list_image_engines auf.
  • 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").
aspect_ratio und resolution werden gegen die Engine geprüft: nano_banana_pro, nano_banana_2_1 und nano_banana_2 akzeptieren 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 bei 1K / 2K / 4K; nano_banana die ersten zehn davon bei 1K; imagen_4 1:1, 16:9, 9:16, 4:3, 3:4 bei 1K / 2K; seedream_4 und flux_1_pro 1:1, 16:9, 9:16, 4:3, 3:4, 21:9 bei 1K. Eine unbekannte Engine oder ein nicht unterstützter Wert liefert 422 mit den gültigen Werten.Trainierte Modelle und color_palette funktionieren nur mit nano_banana_pro, nano_banana_2_1 und nano_banana_2; mit jeder anderen Engine liefern sie 422 — sie werden nie verworfen, und die Engine wird nie gewechselt. Manche Organisationen generieren nur mit ihren trainierten Modellen: dort liefert jede engine 422 — lass engine weg und übergib mindestens ein trainiertes Modell oder eine color_palette.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 — gleich auf jeder Engine.
  • prompt (erforderlich) — wie das Bild bearbeitet werden soll.
  • Genau eines von image_id (ein Bild in deinem Samsa-Kontext, zum Beispiel aus complete_image_upload) oder image_url (eine öffentliche https-URL). Das Seitenverhältnis der Quelle bleibt erhalten.
  • 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) oder kontext (Flux Kontext). Eine unbekannte Engine liefert 422 mit den gültigen Werten. Siehe Engines und Credits.
  • resolution (optional) — 1K (Default), 2K oder 4K auf nano_banana_pro, nano_banana_2 und nano_banana_2_1. gemini und kontext haben eine feste Auflösung: lass resolution dort weg (ein Wert liefert 422).
  • num_images (optional) — 1–4, Default 1.
  • 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.
Trainierte Modelle und color_palette funktionieren nur mit nano_banana_pro (auch wenn du engine weglässt). Nennst du zusammen mit ihnen eine andere Engine, liefert das 422, bevor etwas abgebucht wird — die Engine wird nie gewechselt. Maskierte Edits sind REST-only und laufen auf nano_banana_pro oder gemini.Async — gibt { id, status: "pending", estimated_credits, engine, resolution } zurück. engine und resolution sind die effektiven Werte, mit denen der Edit läuft (resolution ist null auf gemini und kontext). Kosten pro output: 5 Credits × Auflösung auf den drei Nano-Banana-Engines (1K 5, 2K 10, 4K 20), pauschal 5 auf gemini und kontext; × num_images, abgezogen beim Einreichen. Zum Beispiel gibt edit_image(prompt=…, image_id=…, resolution="4K") estimated_credits: 20 zurück.
  • 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.
  • engine (optional) — nano_banana_pro (Default), nano_banana_2 oder nano_banana_2_1 (Nano Banana 2.1).
  • aspect_ratio (optional) — gegen die Liste der Engine validiert (nano_banana_2 und nano_banana_2_1 erlauben 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. 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).
  • engine (optional, Default recraft) — recraft oder ideogram.
  • mode (optional) — default (detailliert, der Default) oder simple. Nur mit engine: "ideogram" gültig; jede andere Kombination wird mit 422 ohne Belastung abgelehnt.
Erzeugt ein SVG. Ein SVG kann kein C2PA-Manifest oder Wasserzeichen tragen, daher wird die Vektorausgabe ohne Signatur ausgeliefert — siehe Content-Provenienz. 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 (jede Engine und jeder Modus); 0 bei einem Cache-Treffer — ein gecachtes Ergebnis zählt nur, wenn es von derselben engine und demselben mode stammt. 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).
  • Kling 4.0 (engine: "kling_4_0") — duration ist jede ganze Sekunde von 3 bis 30, Default 5. Das Tool hat keinen resolution-Parameter, daher ist das Video 720p, mit einer Tonspur, die immer an ist: 15 Credits pro Sekunde (ein 5-s-Clip kostet 75). Bei image_to_video folgt das Video dem Bildausschnitt des Startbilds. Siehe Kling 4.0.
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.
  • 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").processing heißt „erneut abfragen“. Für die Bild-kinds image_generation, image_edit, img2img, image_variation und image_resize gilt:
  • Wenn alle outputs an der Compliance-Pipeline gescheitert sind (zum Beispiel an der C2PA-Signatur), ist der Job failed mit error delivery_blocked_compliance: <codes> und ohne Bilder. Das ist final — hör auf abzufragen.
  • Wenn nur einige outputs daran gescheitert sind, ist der Job completed: images enthält die lieferbaren outputs, und blocked_images listet die anderen als { id, reason }. reason ist compliance_failed_signing, compliance_failed_storage, compliance_failed_watermark oder missing_provenance_state.
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.
MCP-Tool-Argumente können keine Dateibytes tragen. Um eine lokale Bilddatei als Quelle zu nutzen, lädst du sie in drei Schritten hoch:
  1. Rufe prepare_image_upload auf mit:
    • filename (erforderlich) — der Dateiname.
    • content_type (erforderlich) — image/jpeg, image/png oder image/webp.
    • size_bytes (erforderlich) — die exakte Dateigröße in Bytes (zum Beispiel aus wc -c < photo.png). Sie wird in die URL signiert, daher wird ein PUT mit jeder anderen Länge abgelehnt.
    • width, height (optional) — nur genutzt, um ein Bild über 32 MP früh abzulehnen.
    Es gibt { image_id, upload_url, expires_at, max_bytes, allowed_content_types } und einen next_step-String zurück.
  2. PUT die rohen Dateibytes selbst an upload_url, außerhalb von MCP, mit demselben Content-Type und ohne Authorization-Header:
  3. Rufe innerhalb einer Stunde complete_image_upload(image_id) auf.
Limits: höchstens 10 MB (10.485.760 Bytes) und 32 Megapixel; upload_url läuft nach 1 Stunde ab; höchstens 20 Uploads pro Nutzer warten auf ihren Abschluss (too_many_pending_uploads darüber). Das Bild gehört dem aufrufenden Nutzer (dem Ersteller des API-Keys oder dem OAuth-Nutzer) — andere Mitglieder deiner Organisation können es nicht nutzen. Kostenlos. Scope: einer von images.edit, images.transform oder videos.generate. REST-Pendant: Bild-Uploads.
  • image_id (erforderlich) — die id, die prepare_image_upload zurückgegeben hat.
Rufe es nach dem PUT auf. Prüft die gespeicherte Datei (vorhanden, exakt size_bytes, höchstens 10 MB, ein lesbares Bild des vorbereiteten content_type, höchstens 32 Megapixel) und gibt { image_id, status: "completed", filename, content_type, size_bytes, width, height } zurück. Synchron — die image_id ist sofort als Quelle nutzbar für edit_image, img2img, upscale_image, resize_image, create_variations, remove_background, vectorize_image und generate_video (mode: "image_to_video"). Bevor dieser Aufruf gelingt, ist die image_id nirgends nutzbar.Du kannst es gefahrlos erneut aufrufen: Es gibt dasselbe Ergebnis zurück, und ein späterer PUT ändert das abgeschlossene Bild nicht. Eine Datei, die eine Prüfung nicht besteht, liefert einen Validierungsfehler und wird verworfen — PUT eine gültige Datei an dieselbe upload_url, solange sie gültig ist, und rufe dies erneut auf. Eine unbekannte, abgelaufene oder fremde image_id liefert not_found; upload_in_progress heißt, dass gerade ein anderer Aufruf den Upload abschließt — rufe es in ein paar Sekunden erneut auf. Kostenlos. Dieselben Scopes wie prepare_image_upload.