Control API referansı

SimpliGen, uygulama açıkken makinenizde küçük bir HTTP Control API çalıştırır. Bu, MCP sunucusunun konuştuğu aynı API olup, doğrudan SimpliGen'i kendi betikleri, hizmetleri veya ajanlardan yönlendirebilmeniz için sunulur, uygulama sistem tepsisine küçültülü halde bile.

Base URL ve keşif

Sunucu sadece geri döngü bağlantısına bağlanır ve varsayılan olarak şu adrestir:

http://127.0.0.1:48199

Eğer o port meşgulse, SimpliGen işletim sistemi tarafından atanan bir porta geri döner. Geçerli port (ve API sürümü) her zaman uygulamanın kullanıcı veri dizinindeki bir keşif dosyasına yazılır:

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

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

48199 sabit kodlamak yerine canlı portu bulmak için bu dosyayı okuyun.

Kimlik Doğrulama

GET /health hariç her uç nokta Authorization başlığında bir eşleştirme jetonu gerektirir:

Authorization: Bearer sg-agent-xxxxxxxx...

Ayarlar → Ajan Bağla altında uygulamada bir jeton oluşturun (bkz. Ajan Bağla). Ham jeton bir kez gösterilir, sadece bir karma depolanır. Her jeton, bulut nesli için isteğe bağlı bir harcama limiti taşıyabilir. Uygulamada bir jetonu iptal etmek hemen etkili olur.

Eksik veya geçersiz jeton 401 unauthorized döndürür.

Kurallar

• İstekler: JSON gövdeleri (Content-Type: application/json), en fazla 50 MB.
• Yanıtlar: her zaman JSON.
• Hatalar: 2xx olmayan yanıtların şekli { "errorCode": "...", "message": "..." }.
• Kimlikler: ön ayarlar presetId (+ isteğe bağlı packId) ile adreslendirilir, işler jobId ile.

Minimum kimlik doğrulamalı çağrı:

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

Sağlık

GET /health

Canlılık sondası. Kimlik doğrulama yok.

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

Yetenekler

GET /capabilities

Oluşturabileceğiniz her ön ayarı listeler, her bir (preset, mediaType) başına bir giriş, giriş, seçenekler, yerel hazırlığı ve bulut uygunluğu/maliyeti ile.

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

Durum

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

Yerel motor zaten çalışmıyorken başlatır. Gövde almaz.

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

Soğuk bir önyükleme, isteğin beklediğinden daha uzun sürer. Bu gerçekleştiğinde yanıt 202 ile engineStarting: true ve motor önyüklemeye devam eder, bu nedenle GET /status engineRunning doğru olana kadar yoklayın.

Zaten çalışan bir motoru başlatmak 200 ile alreadyRunning: true döndürür ve hiçbir şeyi değiştirmez. Motor yüklü değilse yanıt 409 engine_not_installed: yüklemek multi gigabayt indirme olup uygulama için bir iş değil, API için değil. Motorun çalışmayı reddettiği bir makine 409 engine_unsupported_hardware yanıtı verir, bu yeniden denemek düzeltmez.

POST /engine/stop

Yerel motoru durdurur ve VRAM'ını serbest bırakır. Bulut nesli etkilenmez. Zaten kapalı olan bir motoru durdurmak bir başarıdır.

POST /engine/restart

Onu durdurur ve yeniden başlatır, kilitli bir motor için veya özel bir node yüklendikten veya kaldırıldıktan sonra. Başlatma sırasında 202 davranışı ile aynı, önyükleme istek daha uzun olduğunda.

Projeler

Projeler nesli tutan kaplarıdır.

GET /projects

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

POST /projects

{ "name": "Campaign assets" }

201 ile { "project": { ... } } döndürür. name gereklidir (aksi takdirde 400 invalid_options).

Yüklemeler

Girişler (kaynak görüntüler, referans görüntüler, kaynak videolar) asla yerel yollar olarak geçirilmez. Baytları önce yükleyin ve döndürülen tanıtıcıyı POST /generate öğesine geçirin.

POST /uploads

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

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

Maksimum yükleme 100 MB'tır (413 asset_too_large). Desteklenmeyen uzantılar 400 unsupported_file_type döndürür.

Oluştur

POST /generate

Bir nesil sıraya koyar ve hemen bir jobId ile döner. İşin sonucu için GET /jobs/:id yoklayın (bkz. İşler).

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

Bir bulut işi için yanıt ayrıca "cloudCost": <credits> içerir.

GET /loras

Kullanıcının yüklü LoRA'larını listeler, böylece ajanlar POST /generate öğesinin loras dizisine neyi geçireceğini keşfedebilir. name (görünen ad) üzerinde eşleştirin.

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

LoRA'yı ön ayarın temel modeline (baseModel) uyduğu yerde geçirin ve onu etkinleştirmek için kendi tetik sözcüklerini istemlerinizde kullanın.

İpucu Rehberleri

GET /prompt-guide/:presetId

Ön ayar için ipucu kılavuzunu döndürür: modeli bir ipucuyu nasıl okur, yapıyı ve uzunluğu tercih eder, kamera ve hareket sözcükleri, negatifler, karakterleri nasıl sözcük oluşturur ve çalışılmış örnekler. POST /generate için prompt yazılmadan önce okuyun. Kılavuzlar SimpliGen tarafından sunulur ve önbelleğe alınır, bu nedenle çevrimdışı modda da çalışırlar, açılmadan önce her kılavuzun son kopyasından itibaren.

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

İşler

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 öğesinden biridir. Başarısında, resultPath çözülen yerel dosya yoludur, başarısızlıkta errorMessage nedenini açıklar. Bilinmeyen id 404 job_not_found döndürür.

GET /jobs

En son 25 işi { "jobs": [ ...job... ] } olarak döndürür.

POST /jobs/:id/cancel

Sıraya alınan/çalışan bir işi iptal eder. { "jobId", "status", "note?" } döndürür. Sunucuda uçuştaki bir bulut işi yine de tamamlanabilir (not'ta belirtilir).

Ön Ayarlar Hazırlama

Yerel ön ayarlar ilk kullanımda model dosyalarını indirir. Bunları önceden hazırlayabilirsiniz.

POST /presets/prepare

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

200 { "status": "already_installed" } veya 202 { "status": "started" } döndürür (indirme arka planda çalışır).

GET /presets/prepare

Uçuştaki indirmeleri döndürür: { "downloads": [ ... ] }. Bu veya GET /capabilities (izle localReady), ön ayar hazır olana kadar yoklayın.

Karakterler

Character Studio da komut dosyası uygulanabilir. Karakterler sadece yereldir (bulut reddedilir). Kavramlar için Karakterler bkz.

Tüm nesil uç noktaları, POST /generate gibi GET /jobs/:id aracılığıyla yokladığınız bir jobId döndürür.

Tarifeler

Paket ve ön ayarların dışında çok adımlı tarifeler (akışlar) yazın. Yapı taşlarını keşfedin, üst düzey bir spesifikasyondan oluşturun, ardından isteğe bağlı olarak yayınlayın.

Ürünler ve Konular

Tarifenin subject giriş karakter veya ürün alır. Ürünler diğer konu türüdür: temel fotoğrafı olan, Product Studio ve UGC tarifeleri tarafından kullanılan adlandırılmış şey.

Bir spec üst düzey açıklamadır, uygulama bağlantı noktalarını, adımdan adıma medya zincirini ve adım başına bir ipucu girişini otomatik olarak güçlendirir, ardından doğrular.

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

Oluşturma ve kaydetme, yaratıcı hesaba ihtiyaç duymaz. POST /recipes/:id/publish bağlı bir hesap gerektirir ve not_connected döndürür (needsConnect: true ile) kullanıcı uygulamada bir bağlanana kadar, aynı taslak daha sonra değişmez yayınlanır. Tarifenin kullandığı her ön ayar dağıtılabilir birinci taraf pakete ait olmalıdır.

Video Studio

Filmler Video Studio belgeleridir: zaman çizelgesi üzerinde klipler (işlenecek çekimler) ses parçaları üzerinde. Her düzenleme yolu { change, timeline } yanıtı verir: ne değişti ve bundan sonra filmin zaman çizelgesi (GET /films/:id yanıtlayan aynı şekil). Stüdyo'da açık film değişiklik canlı gösterir ve Ctrl+Z ile geri alır, kapalı film düzenlenir ve kaydedilir.

Klipler yolda kimliğe, ada veya numaraya (zaman çizelgesinde sıraları, en erken önce) göre adlandırılır. Zamanlar saniye veya barlar film bir temposu once: bir konum 3, { "seconds": 3 } veya { "bar": 5 } (bar 1 ilk aşağı atışıdır), uzunluk 5, { "seconds": 5 } veya { "bars": 2 }.

Taslak Yerleştirme

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

Plan bütün olarak önce denetlenir. Sorunları olan plan 400 invalid_plan ile details.problems (örneğin clip 2: ... ile ön eki her şey) ve hiçbir şeyi değiştirmez. mode: "replace" her klipi değiştirir ve klipler çekişleri olmadığı sürece reddedilir "discardTakes": true.

Oluşturur ve Harcama Limiti

Bulut işlemi önceden fiyatlandırılır ve jetonun harcama limitine karşı sayılır: üzeri sınır 402 exceeds_spend_cap yanıtı, bilinmeyen fiyat 503 cost_unknown. Önceki klipten devam eden klipler birer birer işlenir, her başladığı çekmesinden sonra, çağrı hemen yanıtı verir ve GET /films/:id her klibin take gösterir: none, rendering, current, edited, longer, unknown (henüz söylenebilir) veya imported (getirilen video, hiçbir zaman işlenmemiş).

Konumlar

Harcama Sınırları

Jetonun bir harcama sınırı varsa, bulut nesli dağıtmadan önce fiyatlandırılır ve kalan ödenekle aşarsa reddedilir (402 exceeds_spend_cap). Maliyet belirlenemezse (bulut durumu kullanılabilir), sınırlı jeton kapalı 503 cost_unknown ile başarısız olur. Yerel nesli her zaman kredi maliyetinden muaftır.

Tam Bir Akış

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

Hata Kodları