Référence de l'API Control

SimpliGen exécute une petite API Control HTTP sur votre machine tandis 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 avec l'application minimisée dans la barre d'état.

URL de base et découverte

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

http://127.0.0.1:48199

Si ce port est occupé, SimpliGen bascule sur un port attribué par le système d'exploitation. Le port actuel (et la version de l'API) est toujours écrit dans un fichier de découverte du répertoire de 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 en direct plutôt que de coder en dur 48199.

Authentification

Tous les points de terminaison sauf GET /health nécessitent un jeton d'appairage dans l'en-tête Authorization :

Authorization: Bearer sg-agent-xxxxxxxx...

Créez un jeton dans l'application sous Paramètres → Connecter un agent (voir Connecter un agent). Le jeton brut s'affiche une seule fois ; seul un hash est stocké. Chaque jeton peut avoir un plafond de dépenses optionnel pour les générations cloud. Révoquer un jeton dans l'application prend effet immédiatement.

Un jeton manquant ou invalide retourne 401 unauthorized.

Conventions

• Requêtes : 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 présélections sont adressées par presetId (+ packId optionnel) ; les tâches par jobId.

Un appel authentifié minimal :

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

Santé

GET /health

Sonde de vivacité. Pas d'authentification.

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

Capacités

GET /capabilities

Liste chaque présélection avec laquelle vous pouvez générer, une entrée par (preset, mediaType), avec ses entrées, options, disponibilité locale et admissibilité/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 ne s'exécute pas déjà. N'accepte pas de corps.

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

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

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 d'un moteur est un téléchargement de plusieurs gigaoctets et reste une tâche pour l'application, pas pour l'API. Une machine que le moteur refuse d'exécuter répond 409 engine_unsupported_hardware, et réessayer ne le résoudra pas.

POST /engine/stop

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

POST /engine/restart

L'arrête et le relance, pour un moteur bloqué ou après qu'un nœud personnalisé ait été installé ou supprimé. Le même comportement 202 que start quand le démarrage dépasse la requête.

Projets

Les projets sont les conteneurs qui contiennent 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 obligatoire (sinon 400 invalid_options).

Téléchargements

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

POST /uploads

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

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

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

Générer

POST /generate

Met une génération en file d'attente 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 une tâche cloud, la réponse inclut aussi "cloudCost": <credits>.

GET /loras

Liste les LoRAs installées de l'utilisateur pour que les agents découvrent quoi passer dans le tableau loras de POST /generate. Faites correspondre 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 de la présélection (baseModel), et utilisez ses propres mots déclencheurs dans votre invite pour qu'elle s'active.

Guides d'invite

GET /prompt-guide/:presetId

Retourne le guide d'invite pour une présélection : comment son modèle lit une invite, la structure et la longueur qu'il aime, la terminologie caméra et mouvement, les négatifs, comment formuler les caractères, et des exemples fonctionnels. Lisez-le avant d'écrire la prompt pour POST /generate. Les guides sont servis par SimpliGen et mis en cache, ils fonctionnent aussi hors ligne à partir de la dernière copie de chaque guide qui a été ouvert avant.

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

Tâches

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 du fichier local décodé ; en cas d'échec, errorMessage explique pourquoi. Un id inconnu retourne 404 job_not_found.

GET /jobs

Retourne les 25 tâches les plus récentes comme { "jobs": [ ...job... ] }.

POST /jobs/:id/cancel

Annule une tâche en file d'attente ou en cours. Retourne { "jobId", "status", "note?" }. Une tâche cloud déjà en vol peut quand même se terminer sur le serveur (noté dans note).

Préparer les présélections

Les présélections locales 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 cours : { "downloads": [ ... ] }. Interrogez ceci, ou GET /capabilities (observez localReady), jusqu'à ce que la présélection soit prête.

Caractères

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

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

Recettes

Créez des recettes multi-étapes (flux) à partir de packs et présélections. Découvrez les blocs de construction, composez à partir d'une spécification haut niveau, puis publiez optionnellement.

Produits et sujets

L'entrée 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'application auto-câble les ports, la chaîne média étape par étape, et une entrée d'invite 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 n'a besoin d'aucun 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'application ; le même brouillon est alors publié inchangé. Chaque présélection que la recette utilise doit appartenir à un pack distributable propriétaire.

Video Studio

Les films sont des documents Video Studio : des clips (plans à rendre) sur une chronologie sur des pistes audio. Chaque itinéraire d'édition répond { change, timeline } : ce qui a changé, et la chronologie du film après (la même forme que GET /films/:id répond). Avec le film ouvert dans le studio, le changement s'affiche en direct et s'annule avec Ctrl+Z ; un film fermé est édité et sauvegardé.

Les clips sont nommés dans le chemin par id, par name, ou par number (leur ordre sur la chronologie, les plus anciens en premier). Les temps sont en secondes, ou en barres une fois que le film a un tempo : une position est 3, { "seconds": 3 } ou { "bar": 5 } (la barre 1 est le premier temps fort), une longueur est 5, { "seconds": 5 } ou { "bars": 2 }.

Disposer un brouillon

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

Le plan est d'abord vérifié dans son ensemble. Un plan avec des problèmes répond 400 invalid_plan avec chaque problème dans details.problems (chacun préfixé avec son clip, comme clip 2: ...) et ne change rien. mode: "replace" remplace chaque clip et est refusé quand les clips ont des prises sauf si "discardTakes": true.

Rendus et plafond de dépenses

Un rendu cloud est tarifé avant que tout soit mis en file d'attente et décompte du plafond de dépenses du jeton : dépasser le plafond répond 402 exceeds_spend_cap, un prix inconnu 503 cost_unknown. Les clips qui continuent du clip précédent se rendent un à la fois, chacun après la prise d'où il commence ; l'appel répond à la fois, et GET /films/:id affiche la take de chaque clip : none, rendering, current, edited, longer, unknown (cela ne peut pas être dit encore) ou imported (une vidéo apportée, jamais rendue).

Emplacements

Plafonds de dépenses

Quand un jeton a un plafond de dépenses, les générations cloud sont tarifées avant l'expédition et rejetées si elles dépassent l'allocation restante (402 exceeds_spend_cap). Si le coût ne peut pas être déterminé (statut cloud indisponible), un jeton 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