Control API reference

SimpliGen runs a small HTTP Control API on your machine while the app is open. It is the same API the MCP server talks to, exposed directly so you can drive SimpliGen from your own scripts, services, or agents, including with the app minimized to the tray.

Base URL and discovery

The server binds to loopback only and defaults to:

http://127.0.0.1:48199

If that port is taken, SimpliGen falls back to an OS-assigned port. The current port (and API version) is always written to a discovery file in the app's user data directory:

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

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

Read this file to find the live port rather than hardcoding 48199.

Authentication

Every endpoint except GET /health requires a pairing token in the Authorization header:

Authorization: Bearer sg-agent-xxxxxxxx...

Create a token in the app under Settings → Connect an agent (see Connect an agent). The raw token is shown once; only a hash is stored. Each token can carry an optional spend cap for cloud generations. Revoking a token in the app takes effect immediately.

A missing or invalid token returns 401 unauthorized.

Conventions

• Requests: JSON bodies (Content-Type: application/json), up to 50 MB.
• Responses: always JSON.
• Errors: non-2xx responses have the shape { "errorCode": "...", "message": "..." }.
• IDs: presets are addressed by presetId (+ optional packId); jobs by jobId.

A minimal authenticated call:

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

Health

GET /health

Liveness probe. No authentication.

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

Capabilities

GET /capabilities

Lists every preset you can generate with, one entry per (preset, mediaType), with its inputs, options, local readiness, and cloud eligibility/cost.

{
  "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

Starts the local engine when it is not already running. Takes no body.

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

A cold boot takes longer than the request waits. When that happens the reply is 202 with engineStarting: true and the engine keeps booting, so poll GET /status until engineRunning is true.

Starting an engine that already runs returns 200 with alreadyRunning: true and changes nothing. If no engine is installed the reply is 409 engine_not_installed: installing one is a multi gigabyte download and stays a job for the app, not the API. A machine the engine refuses to run on answers 409 engine_unsupported_hardware, which retrying will not fix.

POST /engine/stop

Stops the local engine and frees its VRAM. Cloud generation is unaffected. Stopping an engine that is already down is a success.

POST /engine/restart

Stops and starts it again, for a wedged engine or after a custom node was installed or removed. Same 202 behaviour as start when the boot outlasts the request.

Projects

Projects are the containers that hold generations.

GET /projects

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

POST /projects

{ "name": "Campaign assets" }

Returns 201 with { "project": { ... } }. name is required (400 invalid_options otherwise).

Uploads

Inputs (source images, reference images, source videos) are never passed as local paths. Upload the bytes first and pass the returned handle to POST /generate.

POST /uploads

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

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

Max upload is 100 MB (413 asset_too_large). Unsupported extensions return 400 unsupported_file_type.

Generate

POST /generate

Enqueues a generation and returns immediately with a jobId. Poll GET /jobs/:id (see Jobs) for the result.

{
  "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" }

For a cloud job the response also includes "cloudCost": <credits>.

GET /loras

Lists the user's installed LoRAs so agents can discover what to pass in POST /generate's loras array. Match on name (the display name).

{
  "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 }
  ]
}

Pass the LoRA where it fits the preset's base model (baseModel), and use its own trigger words in your prompt so it activates.

Prompt guides

GET /prompt-guide/:presetId

Returns the prompting guide for a preset: how its model reads a prompt, the structure and length it likes, camera and motion wording, negatives, how to word characters, and worked examples. Read it before writing the prompt for POST /generate. Guides are served by SimpliGen and cached, so they also work offline from the last copy of each guide that was opened before.

{
  "presetId": "z-image-turbo",
  "family": "z-image",
  "familyName": "Z-Image",
  "version": 1,
  "generic": false,
  "text": "# Z-Image prompting guide ...\n\n## Negative prompts in SimpliGen\n...\n\n## Notes for this preset\n\n..."
}

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 is one of queued, processing, completed, failed. On success, resultPath is the decoded local file path; on failure, errorMessage explains why. Unknown id returns 404 job_not_found.

GET /jobs

Returns the 25 most recent jobs as { "jobs": [ ...job... ] }.

POST /jobs/:id/cancel

Cancels a queued/running job. Returns { "jobId", "status", "note?" }. A cloud job already in flight may still complete on the server (noted in note).

Preparing presets

Local presets download their model files on first use. You can prepare them ahead of time.

POST /presets/prepare

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

Returns 200 { "status": "already_installed" } or 202 { "status": "started" } (download runs in the background).

GET /presets/prepare

Returns in-flight downloads: { "downloads": [ ... ] }. Poll this, or GET /capabilities (watch localReady), until the preset is ready.

Characters

Character Studio is scriptable too. Characters are local-only (cloud is rejected). See Characters for the concepts.

All generation endpoints return a jobId you poll via GET /jobs/:id, exactly like POST /generate.

Recipes

Author multi-step recipes (flows) out of packs and presets. Discover the building blocks, compose from a high-level spec, then optionally publish.

Products and subjects

A recipe's subject input takes either a character or a product. Products are the other subject type: a named thing with a base photo, used by Product Studio and UGC recipes.

A spec is a high-level description; the app auto-wires ports, the step-to-step media chain, and a prompt input per step, then validates.

{
  "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" } }
}

Composing and saving needs no creator account. POST /recipes/:id/publish requires a connected account and returns not_connected (with needsConnect: true) until the user connects one in the app; the same draft then publishes unchanged. Every preset the recipe uses must belong to a distributable first-party pack.

Video Studio

Films are Video Studio documents: clips (shots to render) on a timeline over audio tracks. Every editing route answers { change, timeline }: what changed, and the film's timeline after it (the same shape GET /films/:id answers). With the film open in the studio the change shows live and undoes with Ctrl+Z; a closed film is edited and saved.

Clips are named in the path by id, by name, or by number (their order on the timeline, earliest first). Times are seconds, or bars once the film has a tempo: a position is 3, { "seconds": 3 } or { "bar": 5 } (bar 1 is the first downbeat), a length is 5, { "seconds": 5 } or { "bars": 2 }.

Laying out a draft

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 }] }
  ]
}

The plan is checked as a whole first. A plan with problems answers 400 invalid_plan with every problem in details.problems (each prefixed with its clip, such as clip 2: ...) and changes nothing. mode: "replace" replaces every clip and is refused when clips have takes unless "discardTakes": true.

Renders and the spend cap

A cloud render is priced before anything is queued and counts against the token's spend cap: over the cap answers 402 exceeds_spend_cap, an unknown price 503 cost_unknown. Clips that continue from the clip before render one at a time, each after the take it starts from; the call answers at once, and GET /films/:id shows each clip's take: none, rendering, current, edited, longer, unknown (it cannot be told yet) or imported (a video brought in, never rendered).

Locations

Spend caps

When a token has a spend cap, cloud generations are priced before dispatch and rejected if they would exceed the remaining allowance (402 exceeds_spend_cap). If the cost can't be determined (cloud status unavailable), a capped token fails closed with 503 cost_unknown. Local generations are always free of credit cost.

A complete flow

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}'

Error codes