API Dokümantasyonu

HilAPI REST API'si ile Google Imagen 3 altyapısını kullanarak programatik görsel üretin. Tüm istekler https://hilapi.com/api/v1 tabanı üzerinden yapılır.

Kimlik Doğrulama

Tüm isteklerde API anahtarınızı Authorization başlığında gönderin. Anahtarınızı panelinizden oluşturabilirsiniz.

Authorization: Bearer sk-img-xxxxxxxxxxxxxxxxxxxxxxxx

Görsel Üretme

POST /api/v1/designs

Yeni bir görsel üretir. JSON gövde veya multipart/form-data (referans görsel ile) kabul eder.

curl -X POST https://hilapi.com/api/v1/designs \
  -H "Authorization: Bearer sk-img-..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Gün batımında fütüristik bir şehir silüeti",
    "model": "flash"
  }'

Parametreler

Alan	Tip	Açıklama
prompt	string	Görsel açıklaması (referans görsel yoksa zorunlu).
model	string	`flash` (varsayılan) veya `pro`.
referenceImage	file	Opsiyonel referans görsel (multipart, PNG/JPG/WEBP, maks. 10 MB).
async	boolean	`true` gönderirseniz iş kuyruğa alınır, durumunu sorgularsınız.

Modeller

Model	Açıklama
flash	Flash Modu: Hızlı fotoğraf, illüstrasyon ve genel görsel üretimleri için optimize edilmiş sürüm.
pro	Pro Modu: Detaylı kompozisyonlar, şemalar, diyagramlar ve karmaşık nesne ilişkileri gerektiren üretimler için daha yüksek akıl yürütme kapasitesine sahip sürüm.

Yanıt

{
  "success": true,
  "design": {
    "id": "AbC123xYz...",
    "status": "completed",
    "urls": {
      "image":    "/api/v1/designs/AbC123xYz/image",
      "image_2k": "/api/v1/designs/AbC123xYz/image?size=2k",
      "image_4k": "/api/v1/designs/AbC123xYz/image?size=4k"
    }
  }
}

Görseli İndirme

GET /api/v1/designs/:id/image

Üretilen görseli indirir. Format ve boyut parametreleriyle özelleştirin:

Parametre	Değerler	Açıklama
format	`png` \| `jpeg` \| `webp`	Çıktı formatı (varsayılan: png).
size	`2k` \| `4k`	2048px veya 3840px genişliğe yükseltme (Lanczos3).
scale	`1` \| `2` \| `4`	Oransal büyütme (size ile birlikte kullanılmaz).

curl -o gorsel-4k.png \
  -H "Authorization: Bearer sk-img-..." \
  "https://hilapi.com/api/v1/designs/AbC123xYz/image?format=png&size=4k"

Görsel Revize Etme

POST /api/v1/designs/:id/edits

Mevcut bir görseli yeni bir prompt ile revize eder. Kompozisyon korunur.

curl -X POST https://hilapi.com/api/v1/designs/AbC123xYz/edits \
  -H "Authorization: Bearer sk-img-..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Arka planı gece gökyüzü yap", "model": "pro" }'

Diğer Uç Noktalar

Metot	Yol	Açıklama
GET	/api/v1/designs	Görsellerinizi listeler.
GET	/api/v1/designs/:id	Tek görselin detayını / async iş durumunu döndürür.

Hatalar

Tüm hatalar şu yapıda döner:

{ "success": false, "error": { "code": "QUOTA_EXCEEDED", "message": "..." } }

HTTP	Kod	Açıklama
401	MISSING_API_KEY / INVALID_API_KEY	Anahtar eksik veya geçersiz.
403	ACCOUNT_SUSPENDED	Hesap askıya alınmış.
422	CLARIFICATION_NEEDED	Model, prompt hakkında ek bilgi istiyor (yanıtta `question` alanı bulunur).
429	QUOTA_EXCEEDED	Aylık kota doldu. Yanıtta `quota` ve `used` alanları bulunur.
429	RATE_LIMITED	Çok fazla istek. Kısa süre bekleyin.
503	SERVICE_UNAVAILABLE	Üretim servisi geçici olarak kullanılamıyor.

Kotalar

Aylık kotanız planınıza göre belirlenir (Ücretsiz: 50, Pro: 1.000). Başarılı üretim ve revizyonlar kotadan düşer; hatalı istekler düşmez. Anlık kullanımınızı panelinizden takip edebilirsiniz.