Riferimento API di controllo

SimpliGen esegue una piccola API di controllo HTTP sul tuo computer mentre l'app è aperta. È la stessa API con cui parla il server MCP, esposta direttamente affinché tu possa pilotare SimpliGen dai tuoi script, servizi o agent, anche con l'app ridotta a icona nella barra delle applicazioni.

URL di base e scoperta

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

http://127.0.0.1:48199

Se quella porta è occupata, SimpliGen ripiegherà su una porta assegnata dal sistema operativo. La porta corrente (e la versione dell'API) viene sempre scritta in un file di scoperta nella directory dei dati utente 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 piuttosto che codificare hardcoded 48199.

Autenticazione

Ogni endpoint eccetto GET /health richiede un token di accoppiamento nell' intestazione Authorization:

Authorization: Bearer sg-agent-xxxxxxxx...

Crea un token nell'app sotto Impostazioni → Connetti un agente (vedi Connetti un agente). Il token grezzo viene mostrato una sola volta: solo un hash viene archiviato. Ogni token può avere un facoltativo limite di spesa per le generazioni cloud. La revoca di 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 (più facoltativo packId); i job da jobId.

Una chiamata autenticata minima:

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

Salute

GET /health

Sonda di liveness. Nessuna autenticazione.

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

Capacità

GET /capabilities

Elenca ogni preset con cui puoi generare, un'entry 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 richiede corpo.

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

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

L'avvio di 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: l'installazione di uno è un download multi gigabyte e rimane un lavoro per l'app, non per l'API. Una macchina su cui il motore si rifiuta di funzionare risponde 409 engine_unsupported_hardware, che il retry non risolverà.

POST /engine/stop

Arresta il motore locale e libera la sua VRAM. La generazione cloud non è interessata. L'arresto di un motore che è già spento è un successo.

POST /engine/restart

Lo arresta e lo riavvia, per un motore bloccato o dopo che è stato installato o rimosso un nodo personalizzato. Lo 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).

Upload

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 }

L'upload massimo è 100 MB (413 asset_too_large). Le estensioni non supportate restituiscono 400 unsupported_file_type.

Genera

POST /generate

Accoda una generazione e restituisce immediatamente un jobId. Esegui il polling di GET /jobs/:id (vedi Job) 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 agenti 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 parole trigger nel tuo prompt in modo che si attivi.

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. Al successo, resultPath è il percorso del file locale decodificato; al fallimento, errorMessage spiega perché. L'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 o in esecuzione. Restituisce { "jobId", "status", "note?" }. Un job cloud già in volo potrebbe comunque completarsi sul server (annotato in note).

Preparazione dei preset

I preset locali scaricano i loro file di 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 viene eseguito in background).

GET /presets/prepare

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

Caratteri

Character Studio è anch'esso scriptabile. I caratteri sono solo locali (cloud è rifiutato). Vedi Caratteri per i concetti.

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

Ricette

Crea ricette multi-step (flussi) da pack e preset. Scopri i componenti base, componi da una specifica di alto livello, quindi opzionalmente pubblica.

Prodotti e soggetti

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

Uno spec è una descrizione di alto livello; l'app collega automaticamente le porte, la catena media da passaggio a passaggio e un input di prompt per passaggio, quindi convalida.

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

La composizione e il salvataggio non richiedono un account di 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 quindi si pubblica invariata. Ogni preset utilizzato dalla ricetta deve appartenere a un pack di prima parte distribuibile.

Limiti di spesa

Quando un token ha un limite di spesa, le generazioni cloud vengono valutate prima dell'invio e rifiutate se supererebbero l'indennità rimanente (402 exceeds_spend_cap). Se il costo non può essere determinato (lo stato cloud non disponibile), un token coperto non riesce in modo chiuso con 503 cost_unknown. Le generazioni locali sono sempre senza 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