Référence de l'API de contrôle

SimpliGen exécute une petite API de contrôle HTTP sur votre machine pendant que l'application est ouverte. C'est la même API avec laquelle le serveur MCP communique, exposée directement pour que vous puissiez piloter SimpliGen à partir de vos propres scripts, services ou agents, y compris lorsque l'application est réduite dans la barre système.

URL de base et découverte

Le serveur se lie à la loopback uniquement et utilise par défaut :

http://127.0.0.1:48199

Si ce port est occupé, SimpliGen bascule vers un port attribué par le système d'exploitation. Le port actuel (et la version de l'API) sont toujours écrits dans un fichier de découverte dans le répertoire des données utilisateur de l'application :

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

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

Lisez ce fichier pour trouver le port actif plutôt que de coder en dur 48199.

Authentification

Chaque endpoint sauf GET /health nécessite un token d'appairage dans l'en-tête Authorization :

Authorization: Bearer sg-agent-xxxxxxxx...

Créez un token dans l'application sous Paramètres → Connecter un agent (voir Connecter un agent). Le token brut est affiché une seule fois ; seul un hash est stocké. Chaque token peut avoir un plafond de dépense optionnel pour les générations cloud. La révocation d'un token dans l'application prend effet immédiatement.

Un token manquant ou invalide retourne 401 unauthorized.

Conventions

• Demandes : corps JSON (Content-Type: application/json), jusqu'à 50 MB.
• Réponses : toujours JSON.
• Erreurs : les réponses non-2xx ont la forme { "errorCode": "...", "message": "..." }.
• IDs : les presets sont adressés par presetId (+ optionnel packId) ; les jobs par jobId.

Un appel authentifié minimal :

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

Health

GET /health

Sonde de vivacité. Pas d'authentification.

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

Capacités

GET /capabilities

Liste chaque preset avec lequel vous pouvez générer, une entrée par (preset, mediaType), avec ses entrées, options, état de disponibilité locale et éligibilité/coût 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
    }
  ]
}

Statut

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

Démarre le moteur local quand il n'est pas déjà en cours d'exécution. Ne prend pas de corps.

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

Un démarrage à froid prend plus de temps que ce qu'une demande attend. Quand cela se produit, la réponse est 202 avec engineStarting: true et le moteur continue à démarrer, donc interrogez GET /status jusqu'à ce que engineRunning soit vrai.

Le démarrage d'un moteur qui s'exécute déjà retourne 200 avec alreadyRunning: true et ne change rien. Si aucun moteur n'est installé, la réponse est 409 engine_not_installed : l'installation en est un téléchargement de plusieurs gigaoctets et reste une tâche pour l'application, pas pour l'API. Une machine sur laquelle le moteur refuse de s'exécuter répond 409 engine_unsupported_hardware, ce que réessayer ne corrigera pas.

POST /engine/stop

Arrête le moteur local et libère sa VRAM. La génération cloud n'est pas affectée. L'arrêt d'un moteur qui est déjà arrêté est un succès.

POST /engine/restart

L'arrête et le redémarre, pour un moteur bloqué ou après l'installation ou la suppression d'un nœud personnalisé. Le même comportement 202 que start quand le démarrage dépasse la durée de la demande.

Projets

Les projets sont les conteneurs qui conservent les générations.

GET /projects

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

POST /projects

{ "name": "Campaign assets" }

Retourne 201 avec { "project": { ... } }. name est requis (400 invalid_options sinon).

Uploads

Les entrées (images source, images de référence, vidéos source) ne sont jamais passées en tant que chemins locaux. Téléchargez d'abord les octets et passez le handle retourné à POST /generate.

POST /uploads

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

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

Le téléchargement max est 100 MB (413 asset_too_large). Les extensions non supportées retournent 400 unsupported_file_type.

Générer

POST /generate

Met en file d'attente une génération et retourne immédiatement avec un jobId. Interrogez GET /jobs/:id (voir Jobs) pour le résultat.

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

Pour un job cloud, la réponse inclut aussi "cloudCost": <credits>.

GET /loras

Liste les LoRAs installées de l'utilisateur pour que les agents puissent découvrir ce qu'il faut passer dans le tableau loras de POST /generate. Correspondez sur name (le nom d'affichage).

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

Passez la LoRA où elle correspond au modèle de base du preset (baseModel), et utilisez ses propres mots déclencheurs dans votre prompt pour l'activer.

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 est l'un de queued, processing, completed, failed. En cas de succès, resultPath est le chemin de fichier local décodé ; en cas d'échec, errorMessage explique pourquoi. L'id inconnu retourne 404 job_not_found.

GET /jobs

Retourne les 25 jobs les plus récents en tant que { "jobs": [ ...job... ] }.

POST /jobs/:id/cancel

Annule un job en file d'attente/en cours d'exécution. Retourne { "jobId", "status", "note?" }. Un job cloud déjà en vol peut toujours se terminer sur le serveur (noté dans note).

Préparation des presets

Les presets locaux téléchargent leurs fichiers de modèle à la première utilisation. Vous pouvez les préparer à l'avance.

POST /presets/prepare

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

Retourne 200 { "status": "already_installed" } ou 202 { "status": "started" } (le téléchargement s'exécute en arrière-plan).

GET /presets/prepare

Retourne les téléchargements en vol : { "downloads": [ ... ] }. Interrogez cela ou GET /capabilities (regardez localReady), jusqu'à ce que le preset soit prêt.

Caractères

Character Studio est aussi scriptable. Les caractères sont locaux uniquement (cloud est rejeté). Voir Caractères pour les concepts.

Tous les endpoints de génération retournent un jobId que vous interrogez via GET /jobs/:id, exactement comme POST /generate.

Recettes

Authorer des recettes multi-étapes (flux) hors des packs et presets. Découvrir les blocs de construction, composer à partir d'une spec haut niveau, puis éventuellement publier.

Produits et sujets

L'input subject d'une recette prend soit un caractère soit un produit. Les produits sont l'autre type de sujet : une chose nommée avec une photo de base, utilisée par Product Studio et les recettes UGC.

Une spec est une description haut niveau ; l'app auto-câble les ports, la chaîne média étape-à-étape, et un input prompt par étape, puis valide.

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

Composer et sauvegarder ne nécessite pas de compte créateur. POST /recipes/:id/publish nécessite un compte connecté et retourne not_connected (avec needsConnect: true) jusqu'à ce que l'utilisateur en connecte un dans l'app ; le même brouillon publie alors inchangé. Chaque preset utilisé par la recette doit appartenir à un pack propriétaire de première partie distribuable.

Plafonds de dépense

Quand un token a un plafond de dépense, les générations cloud sont tarifées avant dispatch et rejetées si elles dépasseraient l'allocation restante (402 exceeds_spend_cap). Si le coût ne peut pas être déterminé (statut cloud indisponible), un token plafonné échoue fermé avec 503 cost_unknown. Les générations locales sont toujours gratuites en termes de coût de crédit.

Un flux complet

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

Codes d'erreur