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.
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.Parameter
list_models(category?)
list_models(category?)
category(optional) — filtert auf eines vonstyle,object,person,setting.
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.get_model(model_id)
get_model(model_id)
model_id(erforderlich) — die id des Modells.
create_model(name, category, images, …)
create_model(name, category, images, …)
name(erforderlich) — der Modellname.category(erforderlich) — eines vonstyle,object,person,setting.images(erforderlich) — 1–10 Referenzbilder. Jedes ist entweder eine öffentlichehttps-URL (je ≤ 10 MB) oder ein inline base64-Data-URI (data:image/png;base64,…) —image/jpeg,image/pngoderimage/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 alshttps-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) — einehttps-URL, die einmal benachrichtigt wird, sobald das Training einen finalen Status erreicht.
{ 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.update_model(model_id, …)
update_model(model_id, …)
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.
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.list_image_engines()
list_image_engines()
{ 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.improve_prompt(prompt, target, …) — demnächst verfügbar
improve_prompt(prompt, target, …) — demnächst verfügbar
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) —imageodervideo: das Medium, für das der verbesserte Prompt gedacht ist.language(optional) — ein BCP-47-Sprach-Tag wieenoderdefü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, gibtidempotency_in_progresszurü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-HeaderIdempotency-Key.
{ 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.generate_image(prompt, …)
generate_image(prompt, …)
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_4oderflux_1_pro. Lass es weg, umnano_banana_prozu nutzen. Die Limits jeder Engine stehen unter Engines, oder rufelist_image_enginesauf.style_id,object_ids,person_ids,setting_ids(optional) — ids oder Namen trainierter Modelle auslist_modelszum 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, Default1),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.edit_image(prompt, …)
edit_image(prompt, …)
prompt(erforderlich) — wie das Bild bearbeitet werden soll.- Genau eines von
image_id(ein Bild in deinem Samsa-Kontext, zum Beispiel auscomplete_image_upload) oderimage_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) oderkontext(Flux Kontext). Eine unbekannte Engine liefert422mit den gültigen Werten. Siehe Engines und Credits.resolution(optional) —1K(Default),2Koder4Kaufnano_banana_pro,nano_banana_2undnano_banana_2_1.geminiundkontexthaben eine feste Auflösung: lassresolutiondort weg (ein Wert liefert422).num_images(optional) —1–4, Default1.style_id,object_ids,person_ids,setting_ids(optional) — ids oder Namen trainierter Modelle auslist_models, um sie für markenkonforme Edits wiederzuverwenden (ein Name wird zu einem für dich sichtbaren Modell aufgelöst), gleichauf mitgenerate_image.color_palette(optional) — eine anzuwendende Farbpalette, angegeben als Name oder id.
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.img2img(prompt, images, …)
img2img(prompt, images, …)
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_2odernano_banana_2_1(Nano Banana 2.1).aspect_ratio(optional) — gegen die Liste der Engine validiert (nano_banana_2undnano_banana_2_1erlauben zusätzlich4:1,1:4,8:1,1:8); ausgelassen bleibt die Quellform erhalten.resolution(1KDefault,2K,4K),num_outputs(Default1).
get_job_status(kind="img2img", id=…) ab. Kosten:
5 × num_outputs × Auflösung (1K ×1, 2K ×2, 4K ×4). Scope
images.edit.create_variations(image_id | image_url, …)
create_variations(image_id | image_url, …)
- Eines von
image_idoderimage_url(erforderlich). target(optional) — was sich ändern darf:everything(Default),person,object,scene.creativity(optional) —subtleodercreative(Default).variation_instructions/preservation_instructions(optional) — Freitext, je ≤ 2000 Zeichen.num_outputs(1–4, Default1).
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.resize_image(aspect_ratio, image_id | image_url, …)
resize_image(aspect_ratio, image_id | image_url, …)
aspect_ratio(erforderlich) — eines von21:9,16:9,3:2,4:3,5:4,1:1,4:5,3:4,2:3,9:16.- Eines von
image_idoderimage_url(erforderlich). resolution(1KDefault,2K,4K),num_outputs(1–4, Default1).prompt(optional) — Vorgabe für den neu freigelegten Bereich.placement(optional) —{ gravity, scale }, das die Quelle auf der Leinwand positioniert (gravityeines voncenter[Default],top,bottom,left,right,top_left,top_right,bottom_left,bottom_right;scalein(0, 1]).
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.upscale_image(target_resolution, image_id | image_url, …)
upscale_image(target_resolution, image_id | image_url, …)
target_resolution(erforderlich) —2K,4K,6K,8K,10K,12K,14K,16K,20K,24K,28K,32K,38K(Klassen über16Ksind nur mitcrystal).- Eines von
image_idoderimage_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/fractalityin −10..10,engine) oderoptions.magnific_precision(sharpen/smart_grain/ultra_detailin 0..100,flavor).seedvr/crystalnehmen keine Optionen.
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.remove_background(image_id | image_url)
remove_background(image_id | image_url)
- Eines von
image_idoderimage_url(erforderlich).
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.vectorize_image(svg_acceptance, image_id | image_url)
vectorize_image(svg_acceptance, image_id | image_url)
svg_acceptance(erforderlich) — muss der literale Booleantruesein.- Eines von
image_idoderimage_url(erforderlich). engine(optional, Defaultrecraft) —recraftoderideogram.mode(optional) —default(detailliert, der Default) odersimple. Nur mitengine: "ideogram"gültig; jede andere Kombination wird mit422ohne Belastung abgelehnt.
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.generate_video(mode, …)
generate_video(mode, …)
mode(erforderlich) — eines von:image_to_video— animiert einen Startframe. Erfordert genau eines vonimage_id/image_url; optionalend_image_urlbei endframe-fähigen Engines;promptoptional.text_to_video— erfordertprompt.text_to_video_styled— erfordertpromptundstyle_id;object_ids/person_ids/setting_idsoptional, plus eine optionalecolor_palette(Name oder id).
engine(Defaultveo_3_1_lite),duration(Default: die kürzeste von der Engine unterstützte Dauer, in Sekunden),aspect_ratio(Default"16:9"; auch9:16,1:1).- Kling 4.0 (
engine: "kling_4_0") —durationist jede ganze Sekunde von3bis30, Default5. Das Tool hat keinenresolution-Parameter, daher ist das Video720p, mit einer Tonspur, die immer an ist: 15 Credits pro Sekunde (ein 5-s-Clip kostet75). Beiimage_to_videofolgt das Video dem Bildausschnitt des Startbilds. Siehe Kling 4.0.
{ 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.get_job_status(kind, id)
get_job_status(kind, id)
kind(erforderlich) — eines vonimage_generation,image_edit,img2img,image_variation,image_resize,image_upscale,image_background_removal,image_vectorize,videoodermodel. 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.
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
failedmiterrordelivery_blocked_compliance: <codes>und ohne Bilder. Das ist final — hör auf abzufragen. - Wenn nur einige outputs daran gescheitert sind, ist der Job
completed:imagesenthält die lieferbaren outputs, undblocked_imageslistet die anderen als{ id, reason }.reasonistcompliance_failed_signing,compliance_failed_storage,compliance_failed_watermarkodermissing_provenance_state.
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.get_credit_balance()
get_credit_balance()
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.prepare_image_upload(filename, content_type, size_bytes, …)
prepare_image_upload(filename, content_type, size_bytes, …)
-
Rufe
prepare_image_uploadauf mit:filename(erforderlich) — der Dateiname.content_type(erforderlich) —image/jpeg,image/pngoderimage/webp.size_bytes(erforderlich) — die exakte Dateigröße in Bytes (zum Beispiel auswc -c < photo.png). Sie wird in die URL signiert, daher wird einPUTmit jeder anderen Länge abgelehnt.width,height(optional) — nur genutzt, um ein Bild über 32 MP früh abzulehnen.
{ image_id, upload_url, expires_at, max_bytes, allowed_content_types }und einennext_step-String zurück. -
PUTdie rohen Dateibytes selbst anupload_url, außerhalb von MCP, mit demselbenContent-Typeund ohneAuthorization-Header: -
Rufe innerhalb einer Stunde
complete_image_upload(image_id)auf.
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.complete_image_upload(image_id)
complete_image_upload(image_id)
image_id(erforderlich) — die id, dieprepare_image_uploadzurückgegeben hat.
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.