AI araçları API'si

Bir çalışma alanının AI araçlarını kendi uygulamanızdan ya da sunucunuzdan çalıştırın — örneğin bir misafirin özçekimini Görsel Stüdyosu ile etkinliğin çerçeveli portresine dönüştüren bir fotoğraf kabini uygulaması. Bir çalıştırma, konuşmada gelen bir fotoğrafın başlattığıyla birebir aynı kontrollerden geçer: plan, aracın anahtarı, operatörün durdurma düğmesi, kişi ve çalışma alanı limitleri, cüzdan, ölçüm ve otomatik silme.

Başlamadan önce

Panelde Ayarlar → AI → AI araçları → Görsel Stüdyosu → Profiller'i açın, istediğiniz profili düzenleyip API üzerinden izin ver'i açın. API için açılmamış bir profil bu çağrılar için yoktur.
Ayarlar → Geliştirici → API anahtarları'nı açın, bir anahtar oluşturup AI araçlarını çalıştır (tools:run) kapsamını işaretleyin. Belirteç (cwz_…) bir kez gösterilir. Var olan bir anahtara kapsam sonradan aynı sayfadan eklenebilir — belirteci değişmez.

Anahtar bir sunucu kimlik bilgisidir — ticaret API'sinin kullandığıyla aynı türden. Sunucunuzda tutun; tarayıcıya ya da uygulama paketine asla koymayın. Retler: 401 missing_token / unknown_token, 403 revoked_token, 403 missing_scope:tools:run.

1. Profili okuyun

GET /api/tools/image_studio/profiles?locale=tr
Authorization: Bearer cwz_…

{
  "data": [
    {
      "module": "image_studio",
      "profile": "zirve",
      "name": "Zirve 2026",
      "label": "Portreni oluştur",
      "intro": "Bir özçekim yap ya da fotoğraf yükle; stilize bir portre olarak geri al.",
      "formats": [
        { "key": "editorial", "label": "Dergi kapağı" },
        { "key": "pop_art", "label": "Pop art" }
      ],
      "per_day": 3,
      "max_upload_mb": 10,
      "consent": {
        "required": true,
        "text": "Portreni hazırlamak için fotoğrafını bir yapay zekâ görsel servisine göndereceğim. …",
        "version": "9f2c…",
        "accept": "Onaylıyorum",
        "decline": "Vazgeç"
      }
    }
  ]
}

Onayı siz alırsınız ve siz beyan edersiniz. Kişinin fotoğrafını almadan önce consent.text'i gösterin. Kabul ettiğinde çalıştırmayla birlikte consent.version'ı (tam o metnin sha256'sı) gönderin. Çalışma alanı metni değiştirirse sürüm değişir ve eskisi reddedilir — yeni metni gösterip yeniden sorun.

formats profilin hazır stilleridir. Birini format olarak gönderin ya da sürpriz için hiç göndermeyin.

2. Bir çalıştırma başlatın

Örneklerde CWZ_KEY anahtar, CWZ_API panelinizin API'sinin cevap verdiği adrestir.

curl -X POST "$CWZ_API/api/tools/image_studio/runs" \
  -H "Authorization: Bearer $CWZ_KEY" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: 7d3f0b6e-2c4b-4f21-9d1a-0c6b9e1f5a44" \
  -F profile=zirve \
  -F reference=kullanici-4711 \
  -F consent_version=9f2c… \
  -F format=pop_art \
  -F locale=tr \
  -F image=@ozcekim.jpg

Alan
`profile`	Profilin kısa kodu.
`image`	JPEG, PNG ya da WebP; en çok `max_upload_mb`.
`reference`	Kişi için sizin kimliğiniz (en çok 191 karakter). Kişi başına günlük limit buna göre sayılır; kimseye gösterilmez, `DELETE` ile unutulur.
`consent_version`	`consent.required` doğruysa zorunlu.
`format`	İsteğe bağlı: `formats`'tan bir anahtar.
`locale`	İsteğe bağlı: `message`'ın dili.

{
  "data": {
    "id": "0199…",
    "module": "image_studio",
    "profile": "zirve",
    "reference": "kullanici-4711",
    "status": "pending",
    "error_code": null,
    "format": "pop_art",
    "message": "Görselin hazırlanıyor (~30 sn)…",
    "result_available": false,
    "created_at": "2026-10-13T12:00:00+00:00",
    "finished_at": null
  }
}

Cevap çalıştırmayla birlikte 201'dir. Bir kontrolün hemen durdurduğu çalıştırma — kişinin günlük hakkı, duraklatılmış hizmet, boş cüzdan — yine 201'dir: status: "refused", bir error_code ve message'da çalışma alanının kişi için yazdığı cümle. Hiç çalıştırmaya dönüşmeyen çağrılar:

Durum	`error`
404	`module_unavailable`	Araç bu çalışma alanında açık değil
404	`unknown_profile`	Böyle bir profil yok ya da API için açık değil
409	`consent_required`	`consent_version` yok ya da eski — gövde güncel `consent.text` ve `consent.version`'ı taşır
413	`image_too_large`	`max_upload_mb`'den büyük
422	`bad_image`, `unknown_format`	JPEG/PNG/WebP fotoğraf değil; profilde olmayan bir biçim
429		Bu anahtar için çok fazla başlatma — biraz bekleyin
400	`idempotency_key_invalid`	`Idempotency-Key` başlığı boş, 255 karakterden uzun ya da yazdırılabilir ASCII değil
409	`idempotency_key_reused`	Bu `Idempotency-Key` başka bir istekle kullanılmış
409	`idempotency_key_in_progress`	Bu anahtarla gelen ilk istek hâlâ işleniyor — `Retry-After` saniye sonra tekrar deneyin

Güvenle yeniden denemek: `Idempotency-Key`

Bir çalıştırma ücretlidir ve bir ağ hatası çalıştırmanın başlayıp başlamadığını söylemez. Idempotency-Key başlığı gönderin (her yeni çalıştırma için yeni bir UUID) ve aynı anahtarı yalnız o isteği yeniden denerken kullanın:

Aynı anahtar, aynı sunucu anahtarı, aynı istek (alanlar ve fotoğrafın baytları): ilk cevap geri gelir — aynı durum kodu ve gövde, Idempotent-Replayed: true başlığıyla — ve ikinci bir çalıştırma ne başlar ne ücretlenir. Tekrar edilen cevap o anki haliyledir (status: "pending"); güncel durum için çalıştırmayı sorgulayın.
Aynı anahtar, farklı istek: 409 idempotency_key_reused. Yeni çalıştırma için yeni anahtar kullanın.
Aynı anahtarla aynı anda iki istek: biri çalıştırmayı başlatır, diğeri 409 idempotency_key_in_progress alır — bekleyip aynı anahtarla tekrar deneyerek sonucu okuyun.
Anahtarlar bir sunucu anahtarına aittir ve 24 saat saklanır; sonrasında aynı anahtar yeni bir çalıştırma başlatır.
Yalnız çalıştırma oluşturan cevap saklanır. Henüz çalıştırma yokken dönen bir hata (409 consent_required, 413, 422, 404) anahtarı düzeltilmiş istek için boş bırakır.
Başlık olmadan her istek, eskisi gibi, yeni bir çalıştırmadır.

3. Bekleyin

Çalıştırmayı birkaç saniyede bir sorgulayın:

curl "$CWZ_API/api/tools/runs/0199…" \
  -H "Authorization: Bearer $CWZ_KEY" -H "Accept: application/json"

status önce pending, sonra delivered, refused (fotoğraf uygun değildi — kişi yok, çok kişi var, net değil… message bunu çalışma alanının cümlesiyle söyler) ya da failed olur. Bir üretim genelde 20–60 saniye sürer; yavaş olan bir kez kendiliğinden yeniden denenir, vazgeçmeden önce birkaç dakika tanıyın.

Ya da biz haber verelim: bir webhook uç noktasını (panel: Ayarlar → Webhook'lar) tool_run.completed (teslim edildi) ve tool_run.failed (reddedildi ya da başarısız) olaylarına abone edin. Olayın data'sı yukarıdaki çalıştırmanın aynısıdır — diğer her olay gibi imzalı ve hiçbir zaman dosya bağlantısı taşımaz.

4. Sonucu alın

curl "$CWZ_API/api/tools/runs/0199…/result" \
  -H "Authorization: Bearer $CWZ_KEY" -H "Accept: application/json"

{
  "data": {
    "url": "https://…imzali…",
    "expires_at": "2026-10-13T12:06:00+00:00",
    "mime": "image/jpeg",
    "filename": "portrait-1a2b3c4d.jpg",
    "size_bytes": 284311,
    "width": 1080,
    "height": 1350
  }
}

Bağlantı imzalıdır ve birkaç dakika yaşar. Dosyayı indirin; bağlantıyı saklamayın — taze bir tane için yeniden isteyin. Çalıştırma teslim edilmemişken 409 not_ready; otomatik silme ya da sizin DELETE'iniz kaldırdıktan sonra 410 result_deleted.

5. Silin

curl -X DELETE "$CWZ_API/api/tools/runs/0199…" \
  -H "Authorization: Bearer $CWZ_KEY"

204: fotoğraf ve sonuç hemen silinir, reference'ınız unutulur. Çalıştırma satırı, hiçbir görsel olmadan, çalışma alanının kendi muhasebesi için kalır. Tam o anda üretilen bir çalıştırma 409 in_progress döner; kuyruktaki iptal edilir.

DELETE olmadan dosyalar profilin Otomatik silme ayarını, yoksa çalışma alanınınkini izler. İkisi de ayarlanmamışsa (boş ya da 0, varsayılan) hiçbir şey otomatik silinmez: fotoğraf ve sonuç, siz çalıştırmayı DELETE ile silene ya da kişi çalışma alanından verilerinin silinmesini isteyene kadar saklanır. Bir DELETE'ten sonra çalıştırmanın Idempotency-Key'iyle gelen tekrar deneme yine o çalıştırmayı döndürür, reference'ınız olmadan.

API çalıştırmalarının konuşması yoktur: widget'ın Sonucu ziyaretçinin sohbetine de ekle ayarı onlara hiçbir zaman uygulanmaz.

Limitler ve ücret

Kişi başına günlük (reference'a göre), çalışma alanı başına dakikalık ve günlük, aynı anda kaç tane — aracın ve profilin kendi limitleri.
Anahtar başına dakikada başlatma (varsayılan 60), ortak API sınırının üstüne.
Platform anahtarında her başarılı üretim, konuşmadaki gibi çalışma alanının cüzdanından düşer; çalışma alanının kendi sağlayıcı anahtarlarında ücreti sağlayıcı keser.

Her çalıştırma panelde Son çalıştırmalar'da kaynağı API olarak görünür.

Başlamadan önce​

1. Profili okuyun​

2. Bir çalıştırma başlatın​

Güvenle yeniden denemek: Idempotency-Key​

3. Bekleyin​

4. Sonucu alın​

5. Silin​

Limitler ve ücret​