Skip to main content
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 aus dem Pool deiner Organisation, zu denselben Raten wie App und REST API.
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.
  • 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.
  • 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.
  • 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. 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. 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.
  • 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.