Referencia de la API de control

SimpliGen ejecuta una pequeña API de control HTTP en tu máquina mientras la aplicación está abierta. Es la misma API con la que habla el servidor MCP, expuesta directamente para que puedas controlar SimpliGen desde tus propios scripts, servicios o agentes, incluso con la aplicación minimizada en la bandeja.

URL base y descubrimiento

El servidor se vincula solo a loopback y tiene como valor por defecto:

http://127.0.0.1:48199

Si ese puerto está en uso, SimpliGen recurre a un puerto asignado por el sistema operativo. El puerto actual (y la versión de API) siempre se escriben en un archivo de descubrimiento en el directorio de datos del usuario de la aplicación:

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

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

Lee este archivo para encontrar el puerto en vivo en lugar de codificar 48199.

Autenticación

Cada endpoint excepto GET /health requiere un token de emparejamiento en el encabezado Authorization:

Authorization: Bearer sg-agent-xxxxxxxx...

Crea un token en la aplicación en Settings → Connect an agent (ver Conectar un agente). El token sin procesar se muestra una sola vez; solo se almacena un hash. Cada token puede llevar un límite de gasto opcional para generaciones en la nube. Revocar un token en la aplicación tiene efecto inmediatamente.

Un token faltante o inválido devuelve 401 unauthorized.

Convenciones

• Solicitudes: cuerpos JSON (Content-Type: application/json), hasta 50 MB.
• Respuestas: siempre JSON.
• Errores: respuestas que no sean 2xx tienen la forma { "errorCode": "...", "message": "..." }.
• IDs: los presets se direccionan por presetId (+ packId opcional); los trabajos por jobId.

Una llamada autenticada mínima:

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

Salud

GET /health

Sonda de vitalidad. Sin autenticación.

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

Capacidades

GET /capabilities

Lista cada preset con el que puedes generar, una entrada por (preset, mediaType), con sus entradas, opciones, disponibilidad local e idoneidad/costo en la nube.

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

Estado

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

Inicia el motor local cuando no se está ejecutando. Sin cuerpo.

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

Un arranque en frío toma más tiempo del que la solicitud espera. Cuando eso sucede, la respuesta es 202 con engineStarting: true y el motor continúa arrancando, así que sondea GET /status hasta que engineRunning sea verdadero.

Iniciar un motor que ya se está ejecutando devuelve 200 con alreadyRunning: true y no cambia nada. Si no hay motor instalado, la respuesta es 409 engine_not_installed: instalar uno es una descarga de varios gigabytes y permanece como un trabajo para la aplicación, no para la API. Una máquina en la que el motor se niega a ejecutarse responde 409 engine_unsupported_hardware, reintentar no lo solucionará.

POST /engine/stop

Detiene el motor local y libera su VRAM. La generación en la nube no se ve afectada. Detener un motor que ya está parado es un éxito.

POST /engine/restart

Lo detiene e inicia de nuevo, para un motor atascado o después de que se instaló o removió un nodo personalizado. El mismo comportamiento 202 que el inicio cuando el arranque se prolonga más que la solicitud.

Proyectos

Los proyectos son los contenedores que mantienen las generaciones.

GET /projects

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

POST /projects

{ "name": "Campaign assets" }

Devuelve 201 con { "project": { ... } }. name es requerido (de lo contrario 400 invalid_options).

Descargas

Las entradas (imágenes de origen, imágenes de referencia, videos de origen) nunca se pasan como rutas locales. Primero descarga los bytes y pasa el handle devuelto a POST /generate.

POST /uploads

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

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

La descarga máxima es 100 MB (413 asset_too_large). Las extensiones no soportadas devuelven 400 unsupported_file_type.

Generar

POST /generate

Encola una generación y devuelve inmediatamente con un jobId. Sondea GET /jobs/:id (ver Trabajos) para el resultado.

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

Para un trabajo en la nube la respuesta también incluye "cloudCost": <credits>.

GET /loras

Lista las LoRAs instaladas del usuario para que los agentes puedan descubrir qué pasar en el array loras de POST /generate. Coincide en name (el nombre de visualización).

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

Pasa la LoRA donde se ajuste al modelo base del preset (baseModel), y usa sus propias palabras de activación en tu prompt para que se active.

Trabajos

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 es uno de queued, processing, completed, failed. En caso de éxito, resultPath es la ruta del archivo local decodificada; en caso de fallo, errorMessage explica por qué. La id desconocida devuelve 404 job_not_found.

GET /jobs

Devuelve los 25 trabajos más recientes como { "jobs": [ ...job... ] }.

POST /jobs/:id/cancel

Cancela un trabajo en cola o en ejecución. Devuelve { "jobId", "status", "note?" }. Un trabajo en la nube ya en vuelo aún puede completarse en el servidor (anotado en note).

Preparando presets

Los presets locales descargan sus archivos de modelo en el primer uso. Puedes prepararlos con anticipación.

POST /presets/prepare

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

Devuelve 200 { "status": "already_installed" } o 202 { "status": "started" } (la descarga se ejecuta en segundo plano).

GET /presets/prepare

Devuelve descargas en vuelo: { "downloads": [ ... ] }. Sondea esto, o GET /capabilities (observa localReady), hasta que el preset esté listo.

Personajes

Character Studio también es scriptable. Los personajes son solo locales (la nube se rechaza). Ver Personajes para los conceptos.

Todos los endpoints de generación devuelven un jobId que sondeas vía GET /jobs/:id, exactamente como POST /generate.

Recetas

Autor de recetas de varios pasos (flujos) fuera de packs y presets. Descubre los bloques de construcción, compón a partir de una especificación de alto nivel, luego opcionalmente publica.

Productos y sujetos

Un input de subject de una receta toma ya sea un personaje o un producto. Los productos son el otro tipo de asunto: una cosa nombrada con una foto base, utilizada por Product Studio y recetas UGC.

Un spec es una descripción de alto nivel; la aplicación auto-conecta puertos, la cadena de medios de paso a paso, y un input de prompt por paso, luego 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" } }
}

Componer y guardar no necesita una cuenta de creador. POST /recipes/:id/publish requiere una cuenta conectada y devuelve not_connected (con needsConnect: true) hasta que el usuario conecte una en la aplicación; el mismo borrador luego se publica sin cambios. Cada preset que usa la receta debe pertenecer a un pack de primera parte distribuible.

Límites de gasto

Cuando un token tiene un límite de gasto, las generaciones en la nube se cotizan antes del envío y se rechazan si excedieran la asignación restante (402 exceeds_spend_cap). Si el costo no se puede determinar (estado de nube no disponible), un token limitado falla cerrado con 503 cost_unknown. Las generaciones locales siempre son libres de costo de crédito.

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

Códigos de error