AI Agents
MCP-Tool-Referenz
Die Tools, die der SimpliGen MCP Server für KI-Agenten bereitstellt, und die lokale Control API dahinter.
SimpliGen wird mit einem MCP Server (@simpligen/mcp) ausgeliefert, der einen KI-Agenten mit der laufenden SimpliGen App über eine lokale, token-authentifizierte Verbindung verbindet. Der Agent ruft MCP Tools auf; der Server leitet sie an die lokale Control API der App weiter. Siehe Agent verbinden für die Einrichtung.
Tools
| Tool | Was es tut |
|---|---|
list_capabilities | Listet alle Presets auf, mit denen der Agent generieren kann (Bild oder Video), deren Eingaben und Optionen, ob sie lokal verfügbar sind, sowie Cloud-Berechtigung und Kreditkosten. |
get_status | Meldet den Engine-Status, ob Cloud verbunden ist, das Kreditguthaben, das aktive Projekt und den Block characters (Enabled-Flag, installierte Preset-Anzahl für base/edit/i2v und enhancePresets, die Anzahl der installierten Upscale-Presets). |
start_engine | Startet die lokale Engine, falls sie nicht bereits läuft. Gibt den Engine-Status zurück; wenn ein Kaltstart länger als der Aufruf dauert, ist engineStarting wahr und get_status meldet, wann sie aktiv ist. Tut nichts, wenn die Engine bereits läuft, und installiert nie eine fehlende (Connector 0.3.0 oder neuer). |
stop_engine | Stoppt die lokale Engine und gibt ihren VRAM frei. Cloud-Generierung wird nicht beeinträchtigt (Connector 0.3.0 oder neuer). |
restart_engine | Startet die lokale Engine neu, nach Installation oder Entfernung eines Custom Nodes oder wenn sie blockiert ist (Connector 0.3.0 oder neuer). |
list_projects | Listet Projekte auf (die Container, die Generierungen enthalten). |
create_project | Erstellt ein neues Projekt. |
upload_file | Lädt ein lokales Bild oder Video hoch und erhält einen Handle zum Weitergeben an generate. |
list_loras | Listet die installierten Benutzer-LoRAs auf (Name, Basis-Modell, Trigger-Wörter), damit du sie an generate weitergeben kannst. |
generate | Startet eine Bild- oder Videogenerierung. Wähle local, cloud oder auto. Optional loras: [{ name, weight }] weitergeben (lokales Backend, Presets wo inputs.supportsLoras wahr ist; verwende list_loras für Namen) und eine negativePrompt (zusätzliche Begriffe, nach dem Standard des Presets hinzugefügt; bei Cloud-Läufen wird der Preset-Standard unverändert verwendet). options nimmt die benannten Felder (steps, cfg, seed, resolution, aspectRatio, durationSeconds) und jede Advanced Control auf, die das Preset unter list_capabilities → options.controls deklariert, wie unlock, shift oder high_steps, als obere Ebene (Connector 0.2.0 oder neuer). Gibt eine Job-ID zurück. |
get_prompt_guide | Lies den Prompt-Leitfaden für ein Preset (presetId), bevor du den Prompt schreibst: wie das Modell einen Prompt liest, Struktur, Länge, Kamera- und Bewegungswording, Negative, Character-Wording und Beispiele. Die Antwort enthält family, generic (wahr, wenn kein modellspezifischer Leitfaden existiert) und den Leitfaden text. Connector 0.6.0 oder neuer; generate weist Agenten an, ihn zuerst aufzurufen. |
get_job | Ruft Status und Ergebnis eines Jobs ab, einschließlich Ausgabepfad nach Abschluss. |
wait_for_result | Wartet, bis ein Job beendet, fehlgeschlagen oder abgelaufen ist. |
list_jobs | Listet aktuelle Generierungs-Jobs auf. |
cancel_job | Bricht einen in der Warteschlange befindlichen oder laufenden Job ab. |
prepare_preset | Startet das Herunterladen der Modelle eines lokalen Presets, damit es ausführbar wird. |
get_result_image | Gibt das Bild eines abgeschlossenen Jobs inline zur Anzeige zurück. Videobild geben einen Dateipfad zurück. |
list_recipe_blocks | Listet die Bausteine zum Erstellen eines Rezepts auf: Entry Points (Bild oder Video erstellen, Bild bearbeiten, Upscale) und jedes Preset, das als Schritt verwendbar ist, mit seinem Port-Vertrag (benötigte Eingaben, was es erzeugt, zu welchen Entry Points es passt). |
compose_recipe | Erstelle ein neues Rezept aus einer allgemeinen Spezifikation (geordnete Schritte pinned an Presets, plus Eingaben) und speichere es als Entwurf. SimpliGen verdrahtet die Ports, die Schritt-zu-Schritt-Medien-Kette und einen Prompt-Eingang pro Schritt automatisch, dann validiert es. Gibt die Rezept-ID plus Validierung zurück. |
validate_recipe | Probe-Ausführung einer Rezeptspezifikation (oder einer Rohdatei-Config) ohne zu speichern und erhalte präzise Fehler zum Beheben vor dem Erstellen. |
list_recipes | Listet die auf diesem Gerät gespeicherten Rezept-Entwürfe auf. |
get_recipe | Ruft ein gespeichertes Rezept und seine vollständige Config nach ID auf. |
publish_recipe | Reicht ein gespeichertes Rezept beim Creator Marketplace ein (in der Warteschlange zur Überprüfung durch Menschen). Benötigt ein verbundenes Konto; veröffentlicht kostenlos, es sei denn, es ist ein einmaliger Token-Preis festgelegt. |
run_recipe | Führt ein installiertes Rezept (die in UGC Studio und Product Studio, oder einen Entwurf) mit gefüllten Eingaben aus. Eine Subject-Eingabe nimmt eine Zeichen- oder Produkt-ID, Media-Eingaben nehmen Upload-Handles, Text- und Choice-Eingaben nehmen Werte in Klartext. Gleiche Pipeline wie Klicken auf Generate im Studio. Gibt eine Run-ID zurück. |
get_recipe_run | Status einer Rezept-Ausführung: Gesamtstatus, jeder Schritt mit Status und Ergebnis, und finaler Ergebnis-Pfad nach Abschluss. |
wait_for_recipe_run | Blockiert bis eine Rezept-Ausführung beendet ist (oder ein Timeout verstreicht) und gibt die finale Ausführung zurück. |
list_recipe_runs | Aktuelle Ausführungen eines Rezepts mit Status und Ergebnissen. |
cancel_recipe_run | Stoppt eine laufende Rezept-Ausführung. Keine weiteren Schritte starten; ein lokal in-flight Schritt wird unterbrochen. |
list_subjects | Jedes Subject, das die Subject-Eingabe eines Rezepts annehmen kann: Charaktere und Produkte mit ihren IDs. |
list_products | Die auf diesem Gerät gespeicherten Produkte. |
create_product | Speichere ein Produkt aus einem hochgeladenen Foto (Name, Beschreibung, Kategorie), damit Product Studio und UGC-Rezepte es verwenden können. Gibt die Produkt-ID zurück. |
remove_product | Löscht ein Produkt und sein Foto. |
list_characters | Listet alle aktiven Charaktere im Character Studio auf. |
get_character | Ruft die Details und Bilder für einen einzelnen Charakter nach ID auf. |
list_character_features | Listet alle Identitätsmerkmale (Hautfarbe, Haare, etc.) und ihre Optionen auf, zur Verwendung beim Erstellen eines Charakters nach Beschreibung. |
list_character_presets | Listet installierte Presets auf, die für jede Character-Rolle verfügbar sind: Portrait-Basis-Generierung, Identitäts-Bearbeitung, Bild-zu-Video-Animation und Enhancement (Upscale). Jedes Enhancement-Preset umfasst ein supportedScales Array. |
create_character | Erstelle einen neuen Charakter. Unterstützt drei Pfade: describe (generiere ein Basis-Portrait aus Merkmalsauswahl), upload (verwende dein eigenes Bild als Basis) und vision-recreate (von Agent beschriebene Merkmale aus einem Benutzer-Foto). Im Generate-Modus fragt das Tool intern ab, bis das Basis-Portrait bereit ist, und gibt das bereit Character-Objekt zurück. Im Upload-Modus ist der Character sofort bereit. |
generate_character_image | Generiere ein Szenenbild für einen existierenden Charakter per Prompt. Akzeptiert optional presetId, um auszuwählen, welches Identitäts-Edit-Preset für diesen Aufruf verwendet werden soll. Gibt eine oder mehrere Job-IDs zurück zum Polling via wait_for_result. |
generate_character_video | Generiere einen animierten Videoclip für einen existierenden Charakter. Akzeptiert optional framePresetId (Identitäts-Edit-Preset für den Frame-Schritt) und videoPresetId (i2v Preset für den Animate-Schritt). Gibt Job-IDs für Frames und Animation-Schritte zurück. |
generate_character_frame | Generiere einen einzelnen Still-Frame für einen Charakter ohne Animation. Nützlich, wenn du den Frame vor Animation überprüfen oder enhancen möchtest. Akzeptiert optional presetId. Gibt { jobIds: [...] } zurück; verwende jobIds[0] als Frame-Job-ID. |
animate_character | Animiere einen Charakter aus einem abgeschlossenen Frame oder beliebigen abgeschlossenen Bild-Job. Übergib jobId (eine Job-ID aus beliebiger abgeschlossener Generierung) oder filePath (absoluter lokaler Bildpfad). Akzeptiert optional videoPresetId. Gibt eine Video-Job-ID zurück. |
set_character_preset | Setze ein zähes Preset-Standardwert pro Charakter für Bild-Generierung (imagePresetId) und/oder Video-Generierung (videoPresetId). Übergib null, um einen Standard zu löschen. Nachfolgende Aufrufe zu generate_character_image und generate_character_video verwenden diese Defaults, es sei denn, sie werden pro Aufruf überschrieben. |
enhance_character_media | Upscale oder enhance ein Character-Bild oder Video. Quelle kann ein abgeschlossener Job (jobId), eine hochgeladene Datei (filePath Handle) oder das Character-Basis-Portrait (target: 'base') sein. Akzeptiert scale (Upscale-Faktor), keepResolution (upscale dann zurück zu Quellmaße für ein schärferes gleiches-Größe-Ergebnis) und applyAsBase (ersetze das Character-Basis-Portrait mit dem Upscale-Ergebnis). Gibt eine Job-ID zurück. |
regenerate_character_base | Regeneriere das Basis-Portrait für einen existierenden Charakter an Ort und Stelle, optional wechsle zu einem anderen Basis-Preset oder aktualisiere die Identität. Kein neuer Charakter wird erstellt. Fragt intern ab, akzeptiert das neue Basis automatisch und gibt das bereite Character-Objekt zurück. Der Agent muss danach keine Job-ID polling. |
remove_character | Lösche einen Charakter und zugehörige Daten dauerhaft. |
list_films | Listet die Video Studio Filme eines Projekts auf (Connector 0.5.0 oder neuer, wie alle Film-Tools unten). |
create_film | Erstelle einen leeren Film: Form, Auflösung, wo es rendert, Presets pro Shot-Art. Antwortet mit der Timeline. |
get_film | Lese eine Film-Timeline: Tempo, Cast, jeden Clip mit Nummer, Start und Länge in Sekunden und Takten, Shots und Take-Status, die Tracks, Marker und Export-Bereich. |
update_film_settings | Ändere die Film-Form, Auflösung, wo es rendert, Presets, Subject & Style und den Cast und Location, den jeder Clip erbt. |
add_track | Stelle eine hochgeladene Audio-Datei auf die Timeline: Gesang, Musik, Dialog oder Effekte. |
move_track | Verschiebe die Audio eines Tracks, stummschalte ihn, oder setze seine Lautstärke. |
detect_tempo | Setze das Film-Tempo und die Taktlinien vom Song. Danach können Zeiten in Takten angegeben werden. |
add_clip | Füge einen leeren Clip zu einem Moment für eine Länge hinzu. |
update_clip | Schreibe einen Clip in einem Schritt: Shots (Prompt, Länge, gesprochene oder gesungene Linie, wer es sagt, Framing), Cast, Location, wie es startet (neu oder fortgesetzt vom Clip davor; none und frame werden auch akzeptiert, als neu und fortgesetzt), welche Tracks es hört, Preset. |
move_clip | Verschiebe einen Clip zu einem neuen Start oder anderem Video-Weg. |
trim_clip | Ändere die Länge eines Clips oder wo er in seinem Take startet. |
remove_clip | Entferne einen Clip. |
apply_film_plan | Lege einen ganzen Entwurf in einem Schritt aus: Clips auf den Takten mit ihren Shots, Cast und Links. Jedes Problem kommt auf einmal zurück; nichts ändert sich, es sei denn, alles davon ist valid. |
set_fades | Fade einen Clip oder Track ein und aus. |
add_marker | Stelle einen benannten Marker auf das Lineal. |
set_export_range | Exportiere nur Teil des Films oder alles davon. |
render_clips | Rendere die Clips, die es brauchen, oder die benannten. Antwortet sofort mit was gestartet ist, was gehalten wird und den Cloud-Kosten. |
wait_for_renders | Warte bis kein Clip mehr rendert und antworte mit der Timeline. |
list_takes | Listet die Takes eines Clips auf. |
use_take | Mache einen der Takes eines Clips zum angezeigten. |
export_film | Nähe den Film zu einem Video mit seiner Musik zusammen und antworte mit dem Dateipfad. |
list_locations | Listet die Locations der Bibliothek auf. |
create_location | Speichere eine Location aus einem hochgeladenen Bild oder abgeschlossenen Bild-Job. |
Mit dem Film offen im Video Studio erscheint jede Änderung, die ein Agent macht, sofort und wird mit Ctrl+Z rückgängig gemacht. Siehe Ein Agent erstellt ein Musikvideo für eine vollständige Anleitung.
Wie es verbunden ist
Der Agent führt den MCP Server mit npx -y @simpligen/mcp über stdio aus. Der Server authentifiziert sich bei der App mit einem Pairing-Token (SIMPLIGEN_TOKEN) und findet den lokalen Port der App automatisch. Die SimpliGen App muss laufen. Präge einen Token unter Einstellungen in der Sektion "Agent verbinden" aus.
Baust du eine benutzerdefinierte Integration?
Die MCP Tools leiten an eine lokale HTTP Control API weiter, die du direkt aus einer beliebigen Sprache aufrufen kannst. Siehe Control API Referenz.
Ausgabenlimits
Jeder Token kann ein Ausgabenlimit tragen. Ein leeres Limit bedeutet unbegrenzte Cloud-Nutzung, 0 bedeutet nur lokale Generierung und eine positive Zahl begrenzt Cloud-Ausgaben auf viele Guthaben. Lokale Generierung ist immer erlaubt und zählt nie gegen das Limit.
Ein Agent erstellt ein Musikvideo
Geben Sie einem KI-Agent einen Song und ein Ensemble, und beobachten Sie, wie er im Video Studio ein Musikvideo Clip für Clip live zusammenstellt.
Control API-Referenz
Die lokale HTTP-API, die SimpliGen auf Ihrer Maschine bereitstellt, zum Erstellen benutzerdefinierter Integrationen und zum Ausführen von Generierungen im Headless-Modus.