Kontrol API'si başvurusu

SimpliGen, uygulama açıkken makinenizde küçük bir HTTP Kontrol API'si çalıştırır. Bu, MCP sunucusu'nun konuştuğu aynı API'dir ve doğrudan açığa çıkarılmıştır, böylece SimpliGen'i kendi komut dosyalarınızdan, hizmetlerinizden veya ajanlarınızdan yönetebilirsiniz; uygulama tepsiye küçültülü olsa da.

Temel URL ve bulma

Sunucu sadece geri döngüyü bağlayan ve varsayılan olarak şu adrese bağlanır:

http://127.0.0.1:48199

Bu bağlantı noktası meşgulse, SimpliGen bir işletim sistemi tarafından atanan bağlantı noktasına döner. Mevcut bağlantı noktası (ve API sürümü) her zaman uygulamanın kullanıcı veri dizinindeki bir bulma 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 kodlaması yerine canlı bağlantı noktasını bulmak için bu dosyayı okuyun.

Kimlik doğrulama

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

Authorization: Bearer sg-agent-xxxxxxxx...

Uygulamada Ayarlar → Ajan bağla altında bir belirteç oluşturun (bkz. Ajan bağla). Ham belirteç bir kez gösterilir; sadece bir hash depolanır. Her belirteç, bulut kuşaklamalar için isteğe bağlı bir harcama sınırı taşıyabilir. Uygulamada bir belirteci iptal etmek hemen geçerli olur.

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

Kuralları

• İstekler: JSON gövdeleri (Content-Type: application/json), 50 MB'a kadar.
• Yanıtlar: her zaman JSON.
• Hatalar: 2xx olmayan yanıtlar { "errorCode": "...", "message": "..." } şekline sahiptir.
• Kimlikler: ön ayarlar presetId (+ isteğe bağlı packId) ile ele alınır; işler jobId ile.

Minimal bir 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

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

{
  "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 mekanizma çalışmadığında başlatır. Gövde almaz.

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

Soğuk başlatma, isteğin beklediğinden daha uzun sürer. Bu durumda yanıt 202 ve engineStarting: true ile gelir ve mekanizma açılmaya devam eder, bu yüzden GET /status engineRunning doğru olana kadar yokla.

Zaten çalışan bir motoru başlatmak 200 ve alreadyRunning: true döndürür ve hiçbir şeyi değiştirmez. Motor yüklü değilse yanıt 409 engine_not_installed olur: birini yüklemek çok gigabaytlık bir indirmedir ve uygulama için bir iş olmaya devam eder, API için değil. Motorun çalışmasını reddettiği bir makine 409 engine_unsupported_hardware yanıtı verir, yeniden denemek bunu düzeltmez.

POST /engine/stop

Yerel motoru durdurun ve VRAM'ını serbest bırakın. Bulut kuşaklaması etkilenmez. Zaten kapalı olan bir motoru durdurmak başarılı olur.

POST /engine/restart

Durdurun ve yeniden başlatın; takılmış bir motor için veya özel bir düğüm yüklendikten veya kaldırıldıktan sonra. 202 başlat davranışı ile başarısız olur.

Projeler

Projeler kuşaklamaları tutan kaplardı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

Girdiler (kaynak görüntüler, referans görüntüler, kaynak videolar) hiçbir zaman yerel yollar olarak iletilmez. Önce baytları yükleyin ve döndürülen tutamağı POST /generate iletme.

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.

Üretim

POST /generate

Bir kuşaklama enqueues ve hemen bir jobId döndürür. Sonuç için GET /jobs/:id (bkz. İşler) yokla.

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

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

GET /loras

Ajanların POST /generate'in loras dizisine ne ileteceklerini keşfedebilmeleri için kullanıcının yüklü LoRA'larını listeler. name (görüntü adı) ile 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 modelinin (baseModel) uyduğu yere iletin ve kendi tetikleyici kelimelerini isteminize kullanın, böylece etkinleşsin.

İş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 adresinden biridir. Başarıda, resultPath kodlanan yerel dosya yolu; 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

Enqueued/running işi iptal eder. { "jobId", "status", "note?" } döndürür. Zaten uçuşta olan bulut işi sunucuda tamamlanmaya devam edebilir (note'de belirtilmiştir).

Ön ayarları hazırlama

Yerel ön ayarlar ilk kullanımda model dosyalarını indirirler. 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": [ ... ] }. Bunu veya GET /capabilities (saat localReady) yokla, ön ayar hazır olana kadar.

Karakterler

Karakter Stüdyosu da komut dosyası oluşturulabilir. Karakterler yerel-yalnızca (bulut reddedilir). Kavramlar için Karakterler bakın.

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

Tarifler

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

Ürünler ve konular

Bir tarifin subject girdisi bir karakter veya bir ürün alır. Ürünler diğer konu türüdür: bir tarif alabilen bir ürün stüdyosu ve UGC tariflerinde kullanılan temel fotoğraflı adlandırılmış bir şey.

spec, üst düzey bir açıklamadır; uygulama otomatik olarak bağlantı noktalarını, adım-adım medya zincirini ve adım başına bir istemi yapılandırır, 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ı bir hesap gerektirmez. POST /recipes/:id/publish bağlı bir hesap gerektirir ve kullanıcı uygulamada bir tanesini bağlayana kadar not_connected döndürür (needsConnect: true ile); aynı taslak sonra değişmez yayınlanır. Tarifin kullandığı her ön ayar dağıtılabilir birinci taraf pakete ait olmalıdır.

Harcama sınırları

Bir belirtecin harcama sınırı olduğunda, bulut kuşaklamaları gönderimden önce fiyatlandırılır ve kalan avansı aşarlarsa reddedilir (402 exceeds_spend_cap). Maliyet belirlenemezse (bulut durumu kullanılamıyorsa), sınırlı bir belirteç 503 cost_unknown ile kapalı başarısız olur. Yerel kuşaklamalar her zaman kredi maliyetinden muaftır.

Tam 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ı