API Gateway

1. Başlarken & Kimlik Doğrulama

API Gateway ile etkileşime geçmek için tüm HTTP isteklerinizin başlığına (Header) sisteme üye olduktan sonra alacağınız API Key'i eklemeniz gerekmektedir.

Evrensel Base URL

https://apix.hostbakkal.com/api/v1/

Kimlik Doğrulama (Header)

Authorization: Bearer SİZİN_API_ANAHTARINIZ

Bilgi: Tüm kotalarımız ve paket limitlerimiz aylık (30 günlük) olarak yenilenmektedir.

2. Aylık API Paketleri ve İzinler

Sistemimizde yer alan aylık API planlarını ve bu planların desteklediği yapay zeka modellerini aşağıda görebilirsiniz. Satın alma işlemleri için giriş yapmalısınız.

Şu an sistemde aktif paket bulunmuyor.

3. Modelleri Listeleme

Hesabınızın yetkili olduğu ve API üzerinden erişebileceğiniz aktif modelleri bu endpoint üzerinden sorgulayabilirsiniz.

GET /api/v1/models.php

bash

curl https://apix.hostbakkal.com/api/v1/models.php \
  -H "Authorization: Bearer SİZİN_API_ANAHTARINIZ"

4. Metin Üretimi (Chat İsteği)

Yapay zeka modelleriyle etkileşime geçmek ve metin tabanlı yanıtlar almak için ana uç noktamızdır. İstekleriniz doğrudan chat.php dosyasına iletilmelidir.

POST /api/v1/chat.php

Örnek İstek (cURL)

request.sh

curl https://apix.hostbakkal.com/api/v1/chat.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SİZİN_API_ANAHTARINIZ" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "Sen yardımsever bir asistansın."},
      {"role": "user", "content": "Merhaba, nasılsın?"}
    ]
  }'

Örnek Yanıt (JSON)

response.json

{
  "id": "chatcmpl-12345",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Merhaba! Size nasıl yardımcı olabilirim?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 10,
    "total_tokens": 25
  }
}

5. API Anahtarı Harcama Limiti

Harcadıkça Öde kullanırken her API anahtarına ayrı TL bütçesi tanımlanabilir: günlük, haftalık, aylık, yıllık veya ömür boyu. Limit kullanıcı panelinde anahtar oluştururken veya düzenlerken ayarlanır.

Sistem kesinleşmiş harcamayı ve halen çalışan isteklerin ayrılmış tutarını birlikte hesaplar. Bütçe yetersizse istek AI sağlayıcısına gönderilmeden durdurulur.

HTTP 402
{
  "error": {
    "code": "API_SPEND_LIMIT_EXCEEDED",
    "type": "billing_error",
    "status": 402,
    "details": {
      "period": "monthly",
      "period_label": "Aylık",
      "limit_try": 10,
      "spent_try": 8.75,
      "reserved_try": 0.50,
      "remaining_try": 0.75,
      "requested_try": 1.20,
      "reset_at": "..."
    }
  }
}

6. Gelişmiş Gateway Politikaları

Yönetici tarafından ilgili eklentiler etkinleştirildiğinde aşağıdaki politikalar API anahtarına veya gateway yönlendirme katmanına uygulanabilir. Kapalı eklentiler API davranışını değiştirmez.

Özellik	Davranış
Model Alias / Sanal Model	Gerçek provider/model adı yerine sabit bir public model adı kullanılabilir. Alias yalnız anahtarın zaten erişebildiği hedef modeli açar.
Model A/B Test	Tek public model adı, yetkili gerçek modeller arasında ağırlıklı dağıtılabilir. Sticky modda aynı API anahtarı aynı varyanta yönlenir.
Maximum Cost Per Request	PAYG isteği provider'a çıkmadan önce tahmini maksimum TL maliyeti API key politikasını aşarsa istek reddedilir.
Maximum Token Per Request	Input tahmini + izin verilen maksimum output toplamı API key başına sınırlandırılır.
PII Redaction	Yalnız ilgili API anahtarında ayrıca açılmışsa e-posta, telefon, T.C. kimlik ve kart benzeri veriler provider'a gitmeden maskelenir. Orijinal PII redaction istatistiğine yazılmaz.
Provider Maintenance	Planlı bakım aralığındaki provider yeni trafikten çıkarılır; uygun failover varsa otomatik kullanılır.
Backpressure / Waiting Queue	Provider eşzamanlılık kapasitesi dolduğunda yalnız sınırlı süre beklenir; sonsuz bekleme yerine kontrollü `503 BACKPRESSURE_TIMEOUT` döner.
Kademeli Hacim İndirimi	PAYG'de aylık kesinleşmiş harcamaya uyan en yüksek aktif kademe rezervasyon anında snapshotlanır ve o isteğin satış fiyatına uygulanır.

Gerçek SSE Streaming: /v1/chat/completions isteğinde "stream": true gönderildiğinde yanıt text/event-stream olarak parça parça akar. Son olay data: [DONE] satırıdır. Kullanım bilgisini son chunk içinde almak için "stream_options":{"include_usage":true} kullanabilirsiniz. Streaming çağrılarında n=1 zorunludur.

7. Batch API

Batch API eklentisi açıkken çok sayıda Chat Completion veya Embeddings isteğini tek bir asenkron iş olarak kuyruğa alabilirsiniz. Her öğe kendi scope, model, rate-limit, token, maliyet, PII ve faturalama politikalarından bağımsız geçer.

POST /v1/batchesGET /v1/batchesGET /v1/batches/{id}DELETE /v1/batches/{id}

Gerekli scope: oluşturma/iptal için batches:write, listeleme/sonuç için batches:read. Batch içindeki chat/embedding öğesi ayrıca kendi chat:write veya embeddings:write scope'una sahip olmalıdır.

Batch oluşturma örneği

curl -X POST https://apix.hostbakkal.com/v1/batches \
  -H "Authorization: Bearer SİZİN_API_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"custom_id":"soru-1","endpoint":"/v1/chat/completions","body":{"model":"MODEL_ADI","messages":[{"role":"user","content":"Merhaba"}]}},
      {"custom_id":"embed-1","endpoint":"/v1/embeddings","body":{"model":"EMBED_MODEL","input":"örnek metin"}}
    ],
    "metadata":{"source":"nightly-job"}
  }'

Durumlar: queued, processing, completed, partial, failed, cancelled. Geçici 5xx hataları yönetici ayarındaki maksimum deneme sayısına kadar exponential backoff ile tekrar denenebilir.

6. Hata Kodları ve Makine Kodları

KOD	HATA TÜRÜ	AÇIKLAMA
200/202	Başarılı / Kabul edildi	Senkron istek tamamlandı veya asenkron medya işi oluşturuldu.
400	Geçersiz istek	`INVALID_JSON`, `INVALID_MESSAGES`, `MISSING_REQUIRED_FIELD`.
401	Kimlik doğrulama	`AUTHENTICATION_FAILED`.
402	Bakiye / API limiti	`INSUFFICIENT_BALANCE` veya `API_SPEND_LIMIT_EXCEEDED`.
403	Yetki	`ACCOUNT_DISABLED`, `SUBSCRIPTION_REQUIRED`, `MODEL_NOT_ALLOWED`, `IP_NOT_ALLOWED`, `IP_BLOCKED`, `ACCESS_DENIED`.
404	Bulunamadı	`MODEL_NOT_FOUND`, `MEDIA_JOB_NOT_FOUND`, `BATCH_NOT_FOUND`, `BATCH_API_DISABLED`, `ENDPOINT_NOT_FOUND`.
405	Metot	`METHOD_NOT_ALLOWED`.
413	Boyut sınırı	`REQUEST_TOO_LARGE`, `MESSAGE_TOO_LARGE`, `TOO_MANY_MESSAGES`, `BATCH_TOO_LARGE`.
422	İşlenemeyen istek	`UNSUPPORTED_CAPABILITY`, `FORBIDDEN_CONTENT`, `MAX_COST_PER_REQUEST_EXCEEDED`, `MAX_TOKENS_PER_REQUEST_EXCEEDED`.
429	Rate limit / kota	`DAILY_RATE_LIMIT`, `MINUTE_RATE_LIMIT`, `TOKEN_LIMIT_EXCEEDED`, `RATE_LIMIT_EXCEEDED`, `MEDIA_RATE_LIMIT`.
500	Sunucu hatası	`SERVER_ERROR`.
502	Sağlayıcı / medya çıktısı	`PROVIDER_ERROR`, `MEDIA_OUTPUT_INVALID`.
503	Faturalama geçici hatası	`BILLING_MODE_BUSY`, `BILLING_PRICE_MISSING`, `BILLING_FX_MISSING`, `BILLING_UNAVAILABLE`, `POLICY_BACKEND_UNAVAILABLE`, `BACKPRESSURE_TIMEOUT`.

İçindekiler

API Gateway Dokümantasyonu