Riferimento API di controllo

SimpliGen esegue una piccola API HTTP di controllo sul tuo computer mentre l'app è aperta. È la stessa API con cui il server MCP comunica, esposta direttamente in modo da poter controllare SimpliGen dai tuoi script, servizi o agent personalizzati, anche con l'app minimizzata nella system tray.

URL di base e scoperta

Il server si collega solo a loopback e per impostazione predefinita a:

http://127.0.0.1:48199

Se quella porta è occupata, SimpliGen ritorna a una porta assegnata dal SO. La porta corrente (e la versione API) è sempre scritta in un file di scoperta nella directory dati dell'app:

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

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

Leggi questo file per trovare la porta live invece di codificare 48199.

Autenticazione

Ogni endpoint tranne GET /health richiede un token di abbinamento nell'header Authorization:

Authorization: Bearer sg-agent-xxxxxxxx...

Crea un token nell'app in Impostazioni → Collega un agent (vedi Collega un agent). Il token grezzo è mostrato una sola volta; solo un hash viene memorizzato. Ogni token può avere un optional limite di spesa per le generazioni cloud. Revocare un token nell'app ha effetto immediato.

Un token mancante o non valido restituisce 401 unauthorized.

Convenzioni

• Richieste: corpi JSON (Content-Type: application/json), fino a 50 MB.
• Risposte: sempre JSON.
• Errori: le risposte non-2xx hanno la forma { "errorCode": "...", "message": "..." }.
• ID: i preset sono indirizzati da presetId (+ optional packId); i job da jobId.

Una chiamata autenticata minimale:

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

Salute

GET /health

Sonda di vitalità. Nessuna autenticazione.

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

Capacità

GET /capabilities

Elenca ogni preset con cui puoi generare, un elemento per (preset, mediaType), con i suoi input, opzioni, disponibilità locale e idoneità/costo cloud.

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

Stato

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

Avvia il motore locale quando non è già in esecuzione. Non accetta body.

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

Un avvio a freddo richiede più tempo di quello che la richiesta aspetta. Quando ciò accade la risposta è 202 con engineStarting: true e il motore continua l'avvio, quindi esegui il polling di GET /status finché engineRunning non è true.

Avviare un motore che è già in esecuzione restituisce 200 con alreadyRunning: true e non cambia nulla. Se nessun motore è installato la risposta è 409 engine_not_installed: installarne uno è un download di diversi gigabyte e rimane un lavoro per l'app, non per l'API. Una macchina su cui il motore rifiuta di funzionare risponde 409 engine_unsupported_hardware, che i nuovi tentativi non risolveranno.

POST /engine/stop

Arresta il motore locale e libera la sua VRAM. La generazione cloud non è interessata. Arrestare un motore che è già fermo è un successo.

POST /engine/restart

Lo arresta e lo avvia di nuovo, per un motore bloccato o dopo che un nodo personalizzato è stato installato o rimosso. Stesso comportamento 202 di start quando l'avvio dura più della richiesta.

Progetti

I progetti sono i contenitori che contengono le generazioni.

GET /projects

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

POST /projects

{ "name": "Campaign assets" }

Restituisce 201 con { "project": { ... } }. name è obbligatorio (altrimenti 400 invalid_options).

Caricamenti

Gli input (immagini sorgente, immagini di riferimento, video sorgente) non vengono mai passati come percorsi locali. Carica prima i byte e passa l'handle restituito a POST /generate.

POST /uploads

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

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

Il caricamento massimo è di 100 MB (413 asset_too_large). Estensioni non supportate restituiscono 400 unsupported_file_type.

Genera

POST /generate

Mette in coda una generazione e restituisce immediatamente un jobId. Esegui il polling di GET /jobs/:id (vedi Jobs) per il risultato.

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

Per un job cloud la risposta include anche "cloudCost": <credits>.

GET /loras

Elenca le LoRA installate dell'utente in modo che gli agent possano scoprire cosa passare nell'array loras di POST /generate. Abbina su name (il nome visualizzato).

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

Passa la LoRA dove si adatta al modello di base del preset (baseModel), e usa le sue trigger word nel tuo prompt in modo che si attivi.

Guide di prompting

GET /prompt-guide/:presetId

Restituisce la guida di prompting per un preset: come il suo modello legge un prompt, la struttura e la lunghezza che preferisce, la terminologia di camera e movimento, i negativi, come descrivere i personaggi, e esempi funzionanti. Leggila prima di scrivere il prompt per POST /generate. Le guide sono servite da SimpliGen e messe in cache, quindi funzionano anche offline dall'ultima copia di ogni guida che è stata aperta prima.

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

Job

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 è uno di queued, processing, completed, failed. Su successo, resultPath è il percorso del file locale decodificato; su fallimento, errorMessage spiega perché. Un id sconosciuto restituisce 404 job_not_found.

GET /jobs

Restituisce i 25 job più recenti come { "jobs": [ ...job... ] }.

POST /jobs/:id/cancel

Annulla un job in coda/in esecuzione. Restituisce { "jobId", "status", "note?" }. Un job cloud già in volo potrebbe ancora completarsi sul server (annotato in note).

Preparazione dei preset

I preset locali scaricano i loro file modello al primo utilizzo. Puoi prepararli in anticipo.

POST /presets/prepare

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

Restituisce 200 { "status": "already_installed" } o 202 { "status": "started" } (il download funziona in background).

GET /presets/prepare

Restituisce i download in volo: { "downloads": [ ... ] }. Esegui il polling di questo, o di GET /capabilities (osserva localReady), finché il preset non è pronto.

Personaggi

Character Studio è scrivibile anche. I personaggi sono solo locali (il cloud è rifiutato). Vedi Personaggi per i concetti.

Tutti gli endpoint di generazione restituiscono un jobId che esegui il polling via GET /jobs/:id, proprio come POST /generate.

Ricette

Crea ricette multi-step (flussi) dai pack e dai preset. Scopri i blocchi di costruzione, componi da una specifica di alto livello, poi facoltativamente pubblica.

Prodotti e soggetti

Un input subject di una ricetta accetta un personaggio o un prodotto. I prodotti sono l'altro tipo di soggetto: una cosa denominata con una foto di base, usata da Product Studio e dalle ricette UGC.

Una spec è una descrizione di alto livello; l'app auto-collega le porte, la catena media step-by-step, e un input di prompt per ogni step, poi valida.

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

Comporre e salvare non richiede un account creatore. POST /recipes/:id/publish richiede un account connesso e restituisce not_connected (con needsConnect: true) finché l'utente non ne connette uno nell'app; la stessa bozza allora pubblica senza modifiche. Ogni preset che la ricetta usa deve appartenere a un pack di prima parte distribuibile.

Video Studio

I film sono documenti di Video Studio: clip (scene da renderizzare) su una timeline su tracce audio. Ogni rotta di editing risponde con { change, timeline }: cosa è cambiato, e la timeline del film dopo (la stessa forma che GET /films/:id risponde). Con il film aperto nello studio il cambio è mostrato dal vivo e si annulla con Ctrl+Z; un film chiuso è modificato e salvato.

Le clip sono nominate nel percorso per id, per nome, o per numero (il loro ordine sulla timeline, il più antico per primo). I tempi sono secondi, o battute una volta che il film ha un tempo: una posizione è 3, { "seconds": 3 } o { "bar": 5 } (la battuta 1 è il primo downbeat), una lunghezza è 5, { "seconds": 5 } o { "bars": 2 }.

Stendere una bozza

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

Il piano è controllato come un tutto per primo. Un piano con problemi risponde 400 invalid_plan con ogni problema in details.problems (ognuno prefissato con la sua clip, come clip 2: ...) e non cambia nulla. mode: "replace" sostituisce ogni clip ed è rifiutato quando le clip hanno prese a meno che "discardTakes": true.

Render e il limite di spesa

Un render su cloud è prezzato prima che qualsiasi cosa sia messa in coda e conta contro il limite di spesa del token: superare il limite risponde 402 exceeds_spend_cap, un prezzo sconosciuto risponde 503 cost_unknown. Le clip che continuano dalla clip precedente si renderizzano una alla volta, ognuna dopo la presa da cui inizia; la chiamata risponde subito, e GET /films/:id mostra il take di ogni clip: none, rendering, current, edited, longer, unknown (non può ancora essere stabilito) o imported (un video portato dentro, mai renderizzato).

Posizioni

Limiti di spesa

Quando un token ha un limite di spesa, le generazioni su cloud sono prezzate prima dell'invio e rifiutate se supererebbero l'allowance rimanente (402 exceeds_spend_cap). Se il costo non può essere determinato (stato cloud non disponibile), un token limitato fallisce in chiusura con 503 cost_unknown. Le generazioni locali sono sempre libere da costo di credito.

Un flusso completo

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

Codici di errore