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 impulsar 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 predeterminado:

http://127.0.0.1:48199

Si ese puerto está ocupado, SimpliGen recurre a un puerto asignado por el SO. El puerto actual (y versión de API) siempre se escribe en un archivo de descubrimiento en el directorio de datos de 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 activo 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 Configuración → Conectar un agente (consulta 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 surte 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: las respuestas no-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 disponibilidad. 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 aún no se está ejecutando. No toma cuerpo.

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

Un arranque en frío tarda más de lo que la solicitud espera. Cuando eso ocurre, la respuesta es 202 con engineStarting: true y el motor sigue arrancando, así que sondea GET /status hasta que engineRunning sea true.

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 que el motor se niega a ejecutar responde 409 engine_unsupported_hardware, que reintentar no 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á inactivo es un éxito.

POST /engine/restart

Lo detiene e inicia nuevamente, para un motor atascado o después de que un nodo personalizado fue instalado o removido. El mismo comportamiento 202 que start cuando el arranque se prolonga más allá de la solicitud.

Proyectos

Los proyectos son los contenedores que contienen generaciones.

GET /projects

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

POST /projects

{ "name": "Campaign assets" }

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

Cargas

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

POST /uploads

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

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

La carga máxima es de 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 (consulta 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 con name (el nombre de pantalla).

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

Guías de prompting

GET /prompt-guide/:presetId

Devuelve la guía de prompting para un preset: cómo su modelo lee un prompt, la estructura y longitud que le gusta, redacción de cámara y movimiento, negativos, cómo redactar caracteres, y ejemplos trabajados. Léela antes de escribir el prompt para POST /generate. Las guías son servidas por SimpliGen y cacheadas, así que también funcionan sin conexión desde la última copia de cada guía que fue abierta antes.

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

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é. El id desconocido devuelve 404 job_not_found.

GET /jobs

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

POST /jobs/:id/cancel

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

Preparación de 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.

Caracteres

Character Studio también es programable. Los caracteres son solo locales (la nube se rechaza). Consulta Caracteres para los conceptos.

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

Recetas

Autor de recetas de pasos múltiples (flujos) fuera de paquetes y presets. Descubre los bloques de construcción, compone desde una especificación de alto nivel, luego opcionalmente publica.

Productos y sujetos

Un input de subject de la receta toma un carácter o un producto. Los productos son el otro tipo de asunto: algo nombrado con una foto base, usado por Product Studio y recetas UGC.

Un spec es una descripción de alto nivel; la aplicación auto-cablerea puertos, la cadena de medios paso a paso, e 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 borrador mismo se publica sin cambios. Cada preset que usa la receta debe pertenecir a un paquete distributable de primera parte.

Video Studio

Las películas son documentos de Video Studio: clips (tomas para renderizar) en una línea de tiempo sobre pistas de audio. Cada ruta de edición responde { change, timeline }: qué cambió, y la línea de tiempo de la película después (la misma forma que responde GET /films/:id). Con la película abierta en el estudio, el cambio se muestra en vivo y se deshace con Ctrl+Z; una película cerrada se edita y se guarda.

Los clips se nombran en la ruta por id, por nombre, o por número (su orden en la línea de tiempo, más temprano primero). Los tiempos son segundos, o compases una vez que la película tiene un tempo: una posición es 3, { "seconds": 3 } o { "bar": 5 } (el compás 1 es el primer pulso descendente), una longitud es 5, { "seconds": 5 } o { "bars": 2 }.

Diseñando un borrador

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

El plan se verifica como un todo primero. Un plan con problemas responde 400 invalid_plan con cada problema en details.problems (cada uno prefijado con su clip, como clip 2: ...) y no cambia nada. mode: "replace" reemplaza cada clip y se rechaza cuando los clips tienen tomas a menos que "discardTakes": true.

Renderización y el límite de gasto

Un renderizado en la nube se cotiza antes de encolar cualquier cosa y cuenta contra el límite de gasto del token: exceder el límite responde 402 exceeds_spend_cap, un precio desconocido 503 cost_unknown. Los clips que continúan desde el clip anterior se renderizaban uno a la vez, cada uno después de la toma de la que comienza; la llamada responde de una vez, y GET /films/:id muestra el take de cada clip: none, rendering, current, edited, longer, unknown (aún no se puede saber) o imported (un video traído, nunca renderizado).

Ubicaciones

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 excederían la asignación restante (402 exceeds_spend_cap). Si el costo no se puede determinar (estado de la nube no disponible), un token limitado falla de forma cerrada con 503 cost_unknown. Las generaciones locales siempre están 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