Geliştirici rehberi

Temel adres https://kolayzeka.com/api. İki şey çalıştırabilirsiniz: bir model (tek üretim) ya da bir uygulama (birden fazla modeli sırayla çalıştıran hazır akış). İkisi de aynı kurallarla çalışır: asenkron, kredili, webhook'lu. Her modelin ve uygulamanın kendi sayfasında, alanları ve fiyatlarıyla hazır örnekler var: Modeller, Uygulamalar (sayfadaki "API" bağlantısı).

# 1) Bakiye
curl https://kolayzeka.com/api/me -H "Authorization: Bearer $KZ_TOKEN"

# 2) Modelin alanları ve fiyatları
curl https://kolayzeka.com/api/ai-models/openai-gpt-image-2

# 3) Bu girdinin fiyatı (çalıştırmadan)
curl -X POST https://kolayzeka.com/api/models/openai-gpt-image-2/quote \
  -H "Content-Type: application/json" \
  -d '{"input":{"prompt":"kısa bob saç","image":["https://cdn.example.com/selfie.jpg"]}}'

# 4) Çalıştır (202 + id döner)
curl -X POST https://kolayzeka.com/api/models/openai-gpt-image-2/generate \
  -H "Authorization: Bearer $KZ_TOKEN" -H "Content-Type: application/json" \
  -d '{"input":{"prompt":"kısa bob saç","image":["https://cdn.example.com/selfie.jpg"]},
       "webhook_url":"https://your-server.com/hooks/kolayzeka"}'

# 5) Sonuç (ya da webhook'u bekleyin)
curl https://kolayzeka.com/api/generations/<id> -H "Authorization: Bearer $KZ_TOKEN"

Her istekte Authorization: Bearer <token>. Token'ı Profil sayfasında oluşturun; yalnızca bir kez gösterilir, şifre gibi saklayın ve sunucunuzda tutun (mobil uygulamaya gömmeyin). Katalog (/ai-models) ve model teklifi token istemez.

Yanıtlar her zaman JSON'dur; Accept başlığı gerekmez. Gövde JSON ise Content-Type: application/json gönderin.

Başarılı yanıt { success: true, data: … }. Listelerde ayrıca links ve meta (sayfalama: current_page, last_page, total; sonraki sayfa ?page=2). Hata yanıtı { success: false, code, error, … }.

{
  "success": true,
  "data": {
    "id": 42,
    "name": "Acme",
    "email": "[email protected]",
    "credit_balance": 1250
  }
}

Üretimler ve uygulamalar asenkrondur: başlatma isteği 202 ve bir id döner. Sonucu webhook ile alın (önerilen) ya da durum endpoint'ini birkaç saniyede bir sorgulayın. estimated_seconds beklenen süreyi verir.

Sonuç her ikisinde de output_data.result alanındadır (medya için URL, metin için metin).

• Her şey kredi ile ödenir. Fiyat seçtiğiniz seçeneklere göre değişir: kalite, çıktı boyutu, süre, adet. Seçenek başına fiyatlar GET /api/ai-models/{slug} yanıtında mode.pricing (tier anahtarı, ör. 1024x1536|high = boyut × kalite). Daha düşük kalite / boyut daha ucuzdur.
• Kesin fiyat için çalıştırmadan teklif alın: POST /api/models/{slug}/quote ya da POST /api/apps/{slug}/quote. exact: false ise fiyat çıktıya bağlıdır ve teklif tipik değerle hesaplanır.
• Model: kredi istek kabul edilince teklif tutarı kadar ayrılır, iş bitince gerçek tutara göre fark düşülür ya da iade edilir; başarısız olursa tamamı iade edilir. Uygulama: her adım bitince gerçek tutarı düşülür, başarısız adım ücretlendirilmez.
• Ödenen tutar sonuçtaki credit_cost'tur. Bakiye yetmezse 402 insufficient_credits (balance ve required ile).

• Görsel / video / ses alanlarına (value_type = url ya da array<url>) herkese açık bir https URL verin ya da dosyayı multipart/form-data ile yükleyin (input[image]=@./a.jpg, listeler için input[image_urls][]=@./a.jpg; uygulamalarda inputs[…]).
• Çoğu modelin fiyatı girdi görselinin boyutuna değil, istediğiniz çıktıya bağlıdır; yine de büyük fotoğrafları yüklemeden önce küçültmek (ör. ~1 MP, JPEG) yüklemeyi ve işi hızlandırır.
• Sonuç URL'leri imzalıdır ve 24 saat geçerlidir. Kalıcı tutmak için kendi depolamanıza indirin; süresi dolmuşsa işi tekrar GET edince yeni URL gelir.

Başlatma isteğine webhook_url (https) ekleyin. İş bitince imzalı bir POST gelir: { event, success, data }; data durum endpoint'inin döndüğü nesnenin aynısıdır.

Başlıklar: X-KolayZeka-Event, X-KolayZeka-Signature: sha256=<hex>, User-Agent: KolayZeka-Webhook/1.0. İmza, ham gövdenin hesabınızın webhook imzalama anahtarıyla HMAC-SHA256'sıdır. Anahtarı Profil sayfasında oluşturun (anahtar yoksa webhook gönderilmez).

import crypto from 'node:crypto';

// rawBody: the request body exactly as received (before JSON.parse).
const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.KOLAYZEKA_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');
const given = req.headers['x-kolayzeka-signature'] ?? '';

if (given.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given))) {
  return res.status(401).end();
}

$expected = 'sha256='.hash_hmac('sha256', $request->getContent(), config('services.kolayzeka.webhook_secret'));

abort_unless(hash_equals($expected, (string) $request->header('X-KolayZeka-Signature')), 401);

• 2xx dönün. Diğer yanıtlar ve ağ hataları 30 sn arayla en çok 5 kez yeniden denenir.
• Aynı olay birden fazla gelebilir: data.id + event ile tekilleştirin.
• Özel / iç ağ adresleri reddedilir (422 invalid_webhook_url).

Her hata aynı şekildedir. Kodunuzu code'a göre yazın; error kullanıcıya gösterilebilecek insan mesajıdır.

{
  "success": false,
  "code": "insufficient_credits",
  "error": "Yetersiz kredi. Bakiye: 40, Gerekli: 55",
  "balance": 40,
  "required": 55
}

{
  "success": false,
  "code": "validation_failed",
  "error": "Doğrulama başarısız oldu.",
  "errors": {
    "quality": [
      "`quality` alanı şunlardan biri olmalıdır: low, medium, high."
    ]
  }
}

• Sınırlar token başınadır ve iki ayrı kovadır: üretim başlatma (generate, execute, approve) ve sonuç okuma (durum, liste, me, teklifler). Sonuç sorgulamak üretim kotanı harcamaz.
• Her hesap: dakikada 600 üretim, 6000 okuma; aynı anda 6 iş çalışır, fazlası sırada bekler. Daha fazlası gerekirse bize yaz; hesabına özel sınır tanımlarız.
• Giriş (/login): IP başına dakikada 5.
• Aşılırsa 429 rate_limited ve retry_after (saniye). Sorgulama yerine webhook kullanmak sınıra takılmamanın en kolay yolu.