Control API-Referenz

SimpliGen führt eine kleine HTTP Control API auf Ihrer Maschine aus, während die App offen ist. Es ist die gleiche API, mit der der MCP-Server spricht, direkt bereitgestellt, damit Sie SimpliGen von Ihren eigenen Skripten, Services oder Agenten aus steuern können, auch wenn die App auf das Tray minimiert ist.

Basis-URL und Ermittlung

Der Server bindet sich an Loopback-Only und läuft standardmäßig auf:

http://127.0.0.1:48199

Wenn dieser Port belegt ist, greift SimpliGen auf einen vom Betriebssystem zugewiesenen Port zurück. Der aktuelle Port (und die API-Version) wird immer in eine Ermittlungsdatei im Benutzerverzeichnis der App geschrieben:

# Windows
%APPDATA%\simpligen\agent-api.json
# macOS
~/Library/Application Support/simpligen/agent-api.json
# Linux
~/.config/simpligen/agent-api.json

{ "port": 48199, "version": 1 }

Lesen Sie diese Datei, um den aktiven Port zu ermitteln, anstatt 48199 hardcodiert zu verwenden.

Authentifizierung

Jeder Endpoint außer GET /health erfordert ein Pairing-Token im Authorization-Header:

Authorization: Bearer sg-agent-xxxxxxxx...

Erstellen Sie ein Token in der App unter Settings → Connect an agent (siehe Agent verbinden). Das rohe Token wird einmal angezeigt; nur ein Hash wird gespeichert. Jedes Token kann eine optionale Ausgabenbegrenzung für Cloud-Generierungen haben. Das Widerrufen eines Tokens in der App wird sofort wirksam.

Ein fehlendes oder ungültiges Token gibt 401 unauthorized zurück.

Konventionen

• Anfragen: JSON-Textkörper (Content-Type: application/json), bis zu 50 MB.
• Antworten: immer JSON.
• Fehler: Non-2xx-Antworten haben die Form { "errorCode": "...", "message": "..." }.
• IDs: Presets werden durch presetId (+ optionales packId) adressiert; Jobs durch jobId.

Ein minimaler authentifizierter Aufruf:

TOKEN="sg-agent-..."
curl -s http://127.0.0.1:48199/status -H "Authorization: Bearer $TOKEN"

Gesundheit

GET /health

Liveness-Probe. Keine Authentifizierung erforderlich.

{ "ok": true, "name": "simpligen", "version": 1 }

Funktionen

GET /capabilities

Listet jeden Preset auf, mit dem Sie generieren können, einen Eintrag pro (preset, mediaType), mit seinen Eingaben, Optionen, lokaler Bereitschaft und Cloud-Berechtigung/Kosten.

{
  "capabilities": [
    {
      "packId": "local-core-pack",
      "presetId": "z-image-turbo",
      "mediaType": "image",
      "name": "Z-Image Turbo",
      "description": "Ultra-fast, high-quality images in seconds",
      "apiProvider": null,
      "inputs": {
        "acceptsPrompt": true,
        "requiresPrompt": true,
        "requiresImage": false,
        "acceptsReferenceImages": null,
        "acceptsVideo": false,
        "acceptsAudio": false,
        "acceptsReferenceVideos": false,
        "acceptsReferenceAudios": false,
        "supportsLoras": true
      },
      "options": {
        "steps": null,
        "cfg": null,
        "duration": null,
        "resolution": null,
        "aspectRatio": ["1:1", "3:4", "4:3", "9:16", "16:9"]
      },
      "cloudAliasTo": null,
      "localReady": true,
      "cloudEligible": true,
      "cloudCost": 4
    }
  ]
}

Status

GET /status

{
  "engineRunning": true,
  "engineVersion": "v0.26.0",
  "cloudConnected": true,
  "creditBalance": 1280,
  "activeProject": { "id": "default", "name": "My Project" },
  "characters": { "enabled": true, "base": 1, "edit": 1, "i2v": 1, "enhancePresets": 2 }
}

POST /engine/start

Startet die lokale Engine, wenn sie nicht bereits ausgeführt wird. Benötigt keinen Body.

{ "engineRunning": true, "engineVersion": "v0.37.0", "engineStarting": false }

Ein Kaltstart dauert länger, als die Anfrage wartet. In diesem Fall ist die Antwort 202 mit engineStarting: true und die Engine startet weiter. Fragen Sie GET /status ab, bis engineRunning true ist.

Das Starten einer Engine, die bereits läuft, gibt 200 mit alreadyRunning: true zurück und ändert nichts. Wenn keine Engine installiert ist, ist die Antwort 409 engine_not_installed: Das Installieren einer ist ein mehrgigabyte-großer Download und bleibt eine Aufgabe für die App, nicht die API. Eine Maschine, auf der die Engine nicht läuft, antwortet mit 409 engine_unsupported_hardware, das Wiederholen wird das nicht beheben.

POST /engine/stop

Stoppt die lokale Engine und gibt ihr VRAM frei. Cloud-Generierung ist nicht betroffen. Das Stoppen einer Engine, die bereits heruntergefahren ist, ist ein Erfolg.

POST /engine/restart

Stoppt und startet sie erneut, für eine blockierte Engine oder nach der Installation oder dem Entfernen eines benutzerdefinierten Knotens. Das gleiche 202-Verhalten wie beim Start, wenn der Boot die Anfrage überschreitet.

Projekte

Projekte sind die Container, die Generierungen enthalten.

GET /projects

{ "projects": [ { "id": "default", "name": "My Project", "slug": "my-project" } ] }

POST /projects

{ "name": "Campaign assets" }

Gibt 201 mit { "project": { ... } } zurück. name ist erforderlich (400 invalid_options ansonsten).

Uploads

Eingaben (Quellbilder, Referenzbilder, Quellvideos) werden nie als lokale Pfade übergeben. Laden Sie die Bytes zuerst hoch und übergeben Sie den zurückgegebenen Handle an POST /generate.

POST /uploads

{ "filename": "ref.png", "dataBase64": "<base64 of the file bytes>" }

{ "handle": "a1b2c3d4.png", "sizeBytes": 51234 }

Max-Upload ist 100 MB (413 asset_too_large). Nicht unterstützte Erweiterungen geben 400 unsupported_file_type zurück.

Generieren

POST /generate

Reiht eine Generierung ein und gibt sofort jobId zurück. Fragen Sie GET /jobs/:id ab (siehe Jobs) um das Ergebnis zu erhalten.

{
  "presetId": "z-image-turbo",
  "packId": "local-core-pack",
  "mediaType": "image",
  "prompt": "a red fox in the snow, cinematic",
  "backend": "auto",
  "project": "default",
  "image": "a1b2c3d4.png",
  "referenceImages": [{ "handle": "e5f6.png", "label": "style" }],
  "loras": [
    { "name": "RoomLora", "weight": 0.85 },
    { "name": "Mia", "weight": 0.75 }
  ],
  "options": { "aspectRatio": "16:9", "steps": 8, "negativePrompt": "blurry, watermark" }
}

{ "jobId": "gen_abc123", "backend": "local", "status": "queued" }

Für einen Cloud-Job enthält die Antwort auch "cloudCost": <credits>.

GET /loras

Listet die installierten LoRAs des Benutzers auf, damit Agenten ermitteln können, was in das loras-Array von POST /generate übergeben werden soll. Abgleich nach name (dem Anzeigenamen).

{
  "loras": [
    { "name": "RoomLora", "filename": "RoomLora_000002400.safetensors", "baseModel": "flux", "triggerWords": "a room", "defaultStrength": 0.9 },
    { "name": "Mia", "filename": "mia_v2.safetensors", "baseModel": "flux", "triggerWords": "mia", "defaultStrength": 1.0 }
  ]
}

Übergeben Sie die LoRA, wo sie zum Basis-Modell des Presets passt (baseModel), und nutzen Sie seine eigenen Trigger-Wörter in Ihrem Prompt, damit sie aktiviert werden.

Prompt-Guides

GET /prompt-guide/:presetId

Liefert den Prompt-Guide für ein Preset: wie sein Modell einen Prompt liest, welche Struktur und Länge es bevorzugt, Formulierungen für Kamera und Bewegung, negative Prompts, wie Charaktere beschrieben werden, und ausgearbeitete Beispiele. Lesen Sie ihn, bevor Sie den prompt für POST /generate schreiben. Guides werden von SimpliGen bereitgestellt und zwischengespeichert, sodass sie auch offline funktionieren, mit der letzten Kopie jedes Guides, die zuvor geöffnet wurde.

{
  "presetId": "z-image-turbo",
  "family": "z-image",
  "familyName": "Z-Image",
  "version": 1,
  "generic": false,
  "text": "# Z-Image prompting guide ...

## Negative prompts in SimpliGen
...

## Notes for this preset

..."
}

Jobs

GET /jobs/:id

{
  "job": {
    "jobId": "gen_abc123",
    "status": "completed",
    "backend": "local",
    "mediaType": "image",
    "presetId": "z-image-turbo",
    "projectId": "default",
    "resultUrl": "local-file:///C:/Users/you/.../output.png",
    "resultPath": "C:/Users/you/.../output.png",
    "errorMessage": null,
    "createdAt": "2026-06-25T20:00:00.000Z",
    "completedAt": "2026-06-25T20:00:08.000Z"
  }
}

status ist einer von queued, processing, completed, failed. Bei Erfolg ist resultPath der dekodierte lokale Dateipfad; bei Fehler erklärt errorMessage warum. Unbekannte ID gibt 404 job_not_found zurück.

GET /jobs

Gibt die 25 neuesten Jobs als { "jobs": [ ...job... ] } zurück.

POST /jobs/:id/cancel

Bricht einen eingereiht/laufenden Job ab. Gibt { "jobId", "status", "note?" } zurück. Ein Cloud-Job, der bereits im Flug ist, kann auf dem Server trotzdem abgeschlossen werden (in note vermerkt).

Presets vorbereiten

Lokale Presets laden ihre Modelldateien bei der ersten Verwendung herunter. Sie können sie im Voraus vorbereiten.

POST /presets/prepare

{ "presetId": "z-image-turbo", "mediaType": "image" }

Gibt 200 { "status": "already_installed" } oder 202 { "status": "started" } zurück (Download läuft im Hintergrund).

GET /presets/prepare

Gibt laufende Downloads zurück: { "downloads": [ ... ] }. Fragen Sie dies ab, oder GET /capabilities (beobachten Sie localReady), bis der Preset bereit ist.

Charaktere

Character Studio ist ebenfalls skriptierbar. Charaktere sind nur lokal (Cloud wird abgelehnt). Siehe Characters für die Konzepte.

Alle Generierungs-Endpoints geben eine jobId zurück, die Sie genau wie POST /generate über GET /jobs/:id abrufen.

Rezepte

Verfassen Sie mehrstufige Rezepte (Abläufe) aus Packs und Presets. Ermitteln Sie die Bausteine, stellen Sie aus einer High-Level-Spezifikation zusammen und veröffentlichen Sie optional.

Produkte und Subjects

Eine subject-Eingabe eines Rezepts akzeptiert entweder einen Charakter oder ein Produkt. Produkte sind der andere Subject-Typ: ein benanntes Element mit einem Basisfoto, das von Product Studio und UGC-Rezepten verwendet wird.

Eine spec ist eine High-Level-Beschreibung; die App verdrahtet Ports automatisch, die Schritt-zu-Schritt-Medienkette und eine Prompt-Eingabe pro Schritt, dann validiert.

{
  "spec": {
    "name": "Product to spinning video",
    "category": "product",
    "steps": [
      { "preset": "krea2-pack:krea2-turbo" },
      { "preset": "wan-2.2-video-pack:wan-2.2-i2v" }
    ]
  }
}

{
  "recipeId": "b1f2…",
  "valid": true,
  "errors": [],
  "config": { "blocks": [ "…" ], "inputs": [ "…" ], "output": { "from": "n2.video" } }
}

Das Zusammensetzen und Speichern benötigt kein Creator-Konto. POST /recipes/:id/publish erfordert ein verbundenes Konto und gibt not_connected zurück (mit needsConnect: true), bis der Benutzer eines in der App verbindet; der gleiche Entwurf wird dann unverändert veröffentlicht. Jeder Preset, den das Rezept verwendet, muss zu einem verteilbaren First-Party-Pack gehören.

Video Studio

Filme sind Video Studio-Dokumente: Clips (zu rendernde Aufnahmen) auf einer Zeitleiste über Audio-Spuren. Jede Bearbeitungsroute antwortet { change, timeline }: Was geändert wurde und die Zeitleiste des Films danach (die gleiche Form, die GET /films/:id antwortet). Mit dem Film, der im Studio offen ist, wird die Änderung live angezeigt und mit Strg+Z rückgängig gemacht; ein geschlossener Film wird bearbeitet und gespeichert.

Clips werden im Pfad nach ID, Name oder Nummer benannt (ihre Reihenfolge auf der Zeitleiste, am frühesten zuerst). Zeiten sind Sekunden, oder Takte, sobald der Film ein Tempo hat: eine Position ist 3, { "seconds": 3 } oder { "bar": 5 } (Takt 1 ist der erste Downbeat), eine Länge ist 5, { "seconds": 5 } oder { "bars": 2 }.

Einen Entwurf verfassen

POST /films/:id/plan
{
  "mode": "append",
  "cast": ["Kai", "Mira"],
  "location": "Rooftop",
  "clips": [
    { "bars": 2, "shots": [{ "prompt": "@Kai looks over the city", "framing": "wide" }] },
    { "bars": 2, "link": "continue",
      "shots": [{ "prompt": "@Kai sings to camera", "line": "Neon rain", "speaker": "Kai", "framing": "close-up" }] },
    { "bars": 3, "location": "Neon Street", "cast": ["Mira"],
      "shots": [{ "prompt": "@Mira walks through the rain", "seconds": 4 }, { "prompt": "she turns", "seconds": 3 }] }
  ]
}

Der Entwurf wird zuerst als Ganzes überprüft. Ein Entwurf mit Problemen antwortet 400 invalid_plan mit jedem Problem in details.problems (jeweils mit seinem Clip vorangestellt, z. B. clip 2: ...) und ändert nichts. mode: "replace" ersetzt jeden Clip und wird abgelehnt, wenn Clips Takes haben, es sei denn "discardTakes": true.

Renders und Ausgabenbegrenzung

Ein Cloud-Render wird im Voraus bepreist und zählt gegen die Ausgabenbegrenzung des Tokens: über der Begrenzung antwortet 402 exceeds_spend_cap, ein unbekannter Preis 503 cost_unknown. Clips, die vom Clip davor fortgesetzt werden, rendern einzeln, jeder nach dem Take, an den er anschließt; der Aufruf antwortet sofort, und GET /films/:id zeigt die take jedes Clips: none, rendering, current, edited, longer, unknown (es kann noch nicht gesagt werden) oder imported (ein importiertes Video, das nie gerendert wurde).

Orte

Ausgabenbegrenzungen

Wenn ein Token eine Ausgabenbegrenzung hat, werden Cloud-Generierungen vor dem Versand bepreist und abgelehnt, wenn sie die verbleibende Zulage überschreiten würden (402 exceeds_spend_cap). Wenn die Kosten nicht bestimmt werden können (Cloud-Status nicht verfügbar), schlägt ein begrenztes Token geschlossen mit 503 cost_unknown fehl. Lokale Generierungen sind immer kostenlos.

Ein kompletter Ablauf

BASE=http://127.0.0.1:48199
AUTH="Authorization: Bearer sg-agent-..."

# 1. Pick a ready preset
curl -s $BASE/capabilities -H "$AUTH"

# 2. Generate
JOB=$(curl -s $BASE/generate -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"presetId":"z-image-turbo","mediaType":"image","prompt":"a red fox in the snow","options":{"aspectRatio":"16:9"}}' \
  | jq -r .jobId)

# 3. Poll until done, then read resultPath
curl -s $BASE/jobs/$JOB -H "$AUTH" | jq '.job | {status, resultPath, errorMessage}'

Fehlercodes