Control API 参考

SimpliGen 在您的计算机上公开的本地 HTTP API，用于构建自定义集成和无头运行生成。

View as Markdown Open in ChatGPT Open in Claude

当应用程序打开时，SimpliGen 在您的计算机上运行一个小型 HTTP Control API。这是与 MCP 服务器通信的同一 API，直接公开以便您可以从自己的脚本、服务或代理（包括应用最小化到系统托盘时）驱动 SimpliGen。

MCP 与 Control API

如果您只是想让 AI 代理（Claude、Codex 等）使用 SimpliGen，请改为设置 MCP 服务器，它包装了此 API。当您用任何语言编写自定义集成时，直接使用 Control API。

基础 URL 和发现

服务器仅绑定到本地回路并默认为：

http://127.0.0.1:48199

如果该端口已被占用，SimpliGen 将回退到操作系统分配的端口。当前端口（和 API 版本）始终写入应用用户数据目录中的发现文件：

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

agent-api.json

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

读取此文件以找到实时端口，而不是硬编码 48199。

要求

Control API 仅在应用程序打开且机器有权访问代理时运行（这是您许可证的一部分）。仅当 Host 标头是本地回路别名时才提供请求；其他任何内容都会获得 403 forbidden_host（DNS 重绑定防护）。

身份验证

除 GET /health 外的每个端点都需要 Authorization 标头中的配对令牌：

Authorization: Bearer sg-agent-xxxxxxxx...

在应用中的设置 → 连接代理下创建令牌（参见连接代理）。原始令牌仅显示一次；仅存储哈希值。每个令牌可以携带云生成的可选支出上限。在应用中撤销令牌立即生效。

缺失或无效的令牌返回 401 unauthorized。

约定

请求：JSON 正文（Content-Type: application/json），最大 50 MB。
响应：始终为 JSON。
错误：非 2xx 响应的形式为 { "errorCode": "...", "message": "..." }。
ID：预设通过 presetId（加可选 packId）寻址；作业通过 jobId。

最小的已认证调用：

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

健康检查

`GET /health`

活跃性探针。无需身份验证。

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

能力

`GET /capabilities`

列出您可以生成的每个预设，每个 (preset, mediaType) 一个条目，包括其输入、选项、本地就绪情况和云合格性/成本。

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

字段	含义
`localReady`	所有模型文件均已安装；预设现在可以在本地运行。
`cloudEligible`	预设可以在 SimpliGen Cloud 上运行。
`cloudCost`	云运行的近似积分成本（如果不符合条件，则为 null）。
`apiProvider`	对于外部 API 预设（例如 OpenAI、Google），Control API 无法调度，非 null。
`inputs` / `options`	预设接受的内容以及您可能传递给 `POST /generate` 的选项范围/宽高比。`steps`/`cfg` 仅对暴露高级控制的预设非 null。
`inputs.requiresPrompt`	对于指令内置的预设（裁剪、头部或服装交换、放大），为 `false`：空 `prompt` 有效，您发送的任何文本都添加为额外说明。

状态

`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`

当本地引擎尚未运行时启动它。不接受正文。

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

冷启动花费的时间比请求等待的时间更长。发生这种情况时，回复是 202，engineStarting: true，引擎继续启动，所以轮询 GET /status 直到 engineRunning 为 true。

启动已运行的引擎返回 200，alreadyRunning: true，不改变任何内容。如果未安装引擎，回复是 409 engine_not_installed：安装一个是多 GB 下载，且对应用而不是 API 仍是作业。拒绝在其上运行的机器回答 409 engine_unsupported_hardware，重试不会修复。

`POST /engine/stop`

停止本地引擎并释放其 VRAM。云生成不受影响。停止已关闭的引擎是成功的。

`POST /engine/restart`

停止并重新启动它，用于卡顿的引擎或在安装或删除自定义节点后。启动时的 202 行为与启动相同。

项目

项目是容纳生成的容器。

`GET /projects`

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

`POST /projects`

Request

{ "name": "Campaign assets" }

返回 201，带有 { "project": { ... } }。name 必需（否则 400 invalid_options）。

上传

输入（源图像、参考图像、源视频）永远不会作为本地路径传递。先上传字节并将返回的句柄传递给 POST /generate。

`POST /uploads`

Request

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

Response (201)

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

最大上传 100 MB（413 asset_too_large）。不支持的扩展名返回 400 unsupported_file_type。

生成

`POST /generate`

将生成排队并立即返回 jobId。轮询 GET /jobs/:id（参见作业）获取结果。

Request

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

字段	必需	说明
`presetId`	是	来自 `GET /capabilities`。
`mediaType`	是	`"image"` 或 `"video"`。
`packId`	否	如果给定，必须与预设的包匹配。
`prompt`	条件	必需，除非预设报告 `inputs.requiresPrompt: false`。这些预设有内置指令：发送 `""` 按原样运行它们，或添加文本以传递额外说明。
`backend`	否	`"auto"`（默认）、`"local"` 或 `"cloud"`。自动优先选择本地（如已安装），否则云（如已连接）。
`image`	条件	上传句柄。图像到 X 预设需要（`inputs.requiresImage`）。
`video`	条件	上传句柄，用于视频输入预设。
`referenceImages`	条件	句柄数组或 `{ handle, label }`，用于参考图像预设。
`audio`	条件	上传句柄，用于音频驱动预设（唇形同步、音频到视频）。当预设报告 `acceptsAudio` 时必需，否则作业被拒绝，出现 `needs_audio`。
`audioStartSeconds`	否	在轨道中开始的位置，以秒为单位。也在 `options` 下接受。
`referenceVideos`	条件	句柄数组或 `{ handle, soundtrackMode, durationSeconds }`，用于参考剪辑预设。
`referenceAudios`	条件	句柄数组或 `{ handle, durationSeconds }`，用于参考声音预设。
`loras`	否	`{ name, weight }` 数组，用于应用预设（其中 `inputs.supportsLoras` 为 true）。`name` 匹配 LoRA 的显示名称（或文件名）从 `GET /loras`；`weight` 默认为 LoRA 的默认强度。未知名称返回 `400 unknown_lora`。目前仅本地后端。
`project`	否	项目 `id` 或 `slug`。默认为活跃项目。
`options.aspectRatio`	否	必须是预设支持的宽高比之一。
`options.steps` / `options.cfg`	否	在预设公告范围内。
`options.negativePrompt`	否	负提示（UI 的高级选项负面）。也在顶级作为 `negativePrompt` 接受。
`options.durationSeconds`	否	视频持续时间。
`options.resolution`	否	分辨率层标签。

Response (201)

{ "jobId": "gen_abc123", "backend": "local", "status": "queued" }

对于云作业，响应还包括 "cloudCost": <credits>。

后端

外部 API 预设（其中 apiProvider 非 null，例如 GPT Image 2、Veo）无法在此调度，您将获得 400 unsupported_backend。使用本地或 SimpliGen Cloud 预设。云需要连接的账户（400 cloud_not_connected）；本地需要安装模型（400 preset_not_installed，先准备它们）。

`GET /loras`

列出用户已安装的 LoRA，以便代理可以发现在 POST /generate 的 loras 数组中传递什么。在 name（显示名称）上匹配。

Response

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

在预设的基础模型（baseModel）适合的地方传递 LoRA，并在提示中使用其自己的触发词以激活它。

作业

`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 是 queued、processing、completed、failed 之一。成功时，resultPath 是解码的本地文件路径；失败时，errorMessage 解释原因。未知 id 返回 404 job_not_found。

`GET /jobs`

返回最近的 25 个作业为 { "jobs": [ ...job... ] }。

`POST /jobs/:id/cancel`

取消排队/运行的作业。返回 { "jobId", "status", "note?" }。已在中途的云作业可能仍在服务器上完成（在 note 中注明）。

准备预设

本地预设在首次使用时下载其模型文件。您可以提前准备它们。

`POST /presets/prepare`

Request

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

返回 200 { "status": "already_installed" } 或 202 { "status": "started" } （下载在后台运行）。

`GET /presets/prepare`

返回正在进行的下载：{ "downloads": [ ... ] }。轮询此或 GET /capabilities（观察 localReady），直到预设就绪。

角色

角色工作室也是可编程的。角色是仅本地（云被拒绝）。参见角色了解概念。

端点	目的
`GET /characters`	列出角色。
`GET /characters/:id`	获取一个角色。
`GET /character-presets`	已安装的角色预设（基础/编辑/i2v）。
`GET /character-features`	可用的身份/外观特征选项。
`POST /characters`	创建角色（`mode: "generate"` 从描述，或 `"upload"` 从上传的基础图像句柄）。
`POST /characters/:id/generate-image`	生成角色的图像（`{ prompt, aspect?, count?, presetId? }`）。
`POST /characters/:id/generate-frame`	生成单个视频开始帧。
`POST /characters/:id/animate`	将角色动画化为视频。
`POST /characters/:id/preset`	设置角色的默认预设。
`POST /characters/:id/enhance`	放大/增强角色资产。

所有生成端点返回 jobId，您通过 GET /jobs/:id 轮询，与 POST /generate 完全相同。

食谱

从包和预设编写多步食谱（流）。发现构建块，从高级规范组成，然后可选发布。

端点	目的
`GET /recipe-blocks`	入口点 + 每个可用作步骤的预设，及其端口合约。
`POST /recipes/validate`	干运行 `spec`（组成+验证）或 `config`，无保存。返回 `validation`。
`POST /recipes`	从 `spec` 组成并保存草稿。返回 `{ recipeId, valid, errors, config }`。
`GET /recipes`	列出此设备上的每个食谱（从商店安装或在此创建）及其 `inputs`（键、类型、标签、必需、选项）和步骤数。
`GET /recipes/:id`	获取一个食谱，其完整配置，其 `inputs` 和 `readiness`（每步：它运行的预设以及是否在本地安装）。
`POST /recipes/:id/run`	运行食谱。正文：`{ inputs: { key: value }, engine?: "local" \| "cloud" \| "auto" }`。主题输入取字符或产品 id，图像/视频/音频输入取上传句柄，其他所有取普通值。返回 `{ runId, status: "running", engine, steps, cloudCost? }`。云运行预先定价，计入令牌的支出上限。
`GET /recipes/:id/runs`	食谱的最近运行，最新优先。
`GET /recipe-runs/:id`	运行的状态：`status`（运行中、已完成、失败、已取消），`steps`（每个包含状态、作业 id 和结果路径）和一旦最后媒体步骤完成，`resultPath`。
`POST /recipe-runs/:id/cancel`	停止运行。不再启动进一步步骤；本地中途步骤被中断。
`POST /recipes/:id/publish`	提交到创意市场（需要连接的账户）。

产品和主题

食谱的 subject 输入取字符或产品。产品是另一种主题类型：具有基础照片的命名事物，由产品工作室和 UGC 食谱使用。

端点	目的
`GET /subjects`	食谱可以取的每个主题：角色和产品（`id`、`type`、`name`、`status`）。
`GET /products`	列出产品。
`GET /products/:id`	获取一个产品。
`POST /products`	从上传照片创建产品：`{ name, image: <upload handle>, description?, category? }`。描述和类别被编织到食谱提示中。返回 `{ productId, product }`。
`DELETE /products/:id`	删除产品及其照片。

spec 是高级描述；应用自动连接端口、步骤到步骤的媒体链和每步的提示输入，然后验证。

POST /recipes request

{
  "spec": {
    "name": "Product to spinning video",
    "category": "product",
    "steps": [
      { "preset": "krea2-pack:krea2-turbo" },
      { "preset": "wan-2.2-video-pack:wan-2.2-i2v" }
    ]
  }
}

Response (201)

{
  "recipeId": "b1f2…",
  "valid": true,
  "errors": [],
  "config": { "blocks": [ "…" ], "inputs": [ "…" ], "output": { "from": "n2.video" } }
}

组成和保存不需要创意账户。POST /recipes/:id/publish 需要连接的账户，返回 not_connected（带 needsConnect: true）直到用户在应用中连接一个；同一草稿然后未更改发布。食谱使用的每个预设必须属于可分配的第一方包。

支出上限

当令牌有支出上限时，云生成在调度前定价，如果它们会超过剩余额度，则被拒绝（402 exceeds_spend_cap）。如果成本无法确定（云状态不可用），上限令牌失败关闭，出现 503 cost_unknown。本地生成总是不产生信用成本。

完整流程

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

错误代码

HTTP	`errorCode`	时间
400	`invalid_json`	正文不是有效的 JSON。
400	`invalid_options`	必需字段缺失或格式错误。
400	`invalid_preset`	预设/包/mediaType 不匹配。
400	`needs_*`	必需输入（提示、图像、参考）缺失。
400	`invalid_handle`	输入不是有效的上传句柄。
400	`unsupported_backend`	预设在外部 API 上运行。
400	`preset_not_installed`	选择本地后端但模型未安装。
400	`cloud_not_connected`	选择云后端但未连接账户。
401	`unauthorized`	令牌缺失或无效。
402	`exceeds_spend_cap`	云成本超过令牌的支出上限。
403	`forbidden_host`	非本地回路 `Host` 标头。
404	`not_found` / `invalid_preset` / `job_not_found`	未知路由、预设或作业。
413	`asset_too_large`	上传超过 100 MB。
503	`cost_unknown`	上限令牌；云成本无法确定。
500	`internal_error`	意外服务器错误。

Control API 参考

On this page