🚀 API Havuz Yönetim Sistemi

1. Genel Bakış

Bu API, OpenAI API formatıyla tam uyumlu bir gateway sistemidir. Arkada birden fazla AI sağlayıcısının (Google Gemini, OpenAI, Anthropic vb.) API anahtarlarını havuzlar ve akıllı yük dengeleme ile failover sağlar.

Temel Özellikler

• OpenAI SDK Uyumluluğu: Mevcut OpenAI SDK'larınızı direkt kullanabilirsiniz
• Otomatik Failover: Bir API key hata verirse otomatik olarak diğerine geçer
• Akıllı Key Seçimi: Öncelik, hata sayısı ve kullanım oranına göre en uygun key seçilir
• Maliyet Takibi: Her istek için token ve maliyet hesaplanır
• Rate Limit Yönetimi: API key bazında rate limit kontrolü
• Proje Bazlı Erişim: Her projeye özel API anahtarı ve model kısıtlamaları

Base URL

https://api.pixellab.com.tr/api/v1

2. Kimlik Doğrulama

API'ye erişmek için size verilen proje API anahtarını kullanmanız gerekir. API anahtarı iki şekilde gönderilebilir:

Yöntem 1: Authorization Header (Önerilen)

Authorization: Bearer pk_live_your_api_key_here

Yöntem 2: X-API-Key Header

X-API-Key: pk_live_your_api_key_here

Yöntem 3: Query Parameter

GET /v1/models?api_key=pk_live_your_api_key_here

API Anahtarı Formatı

3. Chat Completions API

Sohbet tamamlama endpoint'i, mesaj listesi alır ve AI modelinden yanıt üretir. OpenAI'nin Chat Completions API'si ile tam uyumludur.

curl -X POST "https://api.pixellab.com.tr/api/v1/chat/completions" \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [
      {"role": "system", "content": "Sen yardımcı bir asistansın."},
      {"role": "user", "content": "Merhaba, nasılsın?"}
    ],
    "temperature": 0.7,
    "max_tokens": 1000
  }'

{
  "id": "chatcmpl-abc123def456",
  "object": "chat.completion",
  "created": 1704056400,
  "model": "gemini-2.0-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Merhaba! Ben bir yapay zeka asistanıyım, bu yüzden gerçek anlamda bir ruh halim yok. Ama size yardımcı olmaya hazırım! Size nasıl yardımcı olabilirim?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 42,
    "total_tokens": 67
  }
}

Streaming Yanıtlar

stream: true parametresi ile yanıtlar parça parça (chunk) olarak gelir. Bu, kullanıcıya daha hızlı geri bildirim sağlar.

Streaming İstek

curl -X POST "https://api.pixellab.com.tr/api/v1/chat/completions" \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [{"role": "user", "content": "Kısa bir hikaye yaz"}],
    "stream": true
  }'

Streaming Yanıt Formatı (SSE)

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"Bir"},"index":0}]}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":" zamanlar"},"index":0}]}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":" bir"},"index":0}]}

data: [DONE]

4. Models API

Projenizin erişebildiği modellerin listesini döner. Her proje farklı modellere erişim iznine sahip olabilir.

curl -X GET "https://api.pixellab.com.tr/api/v1/models" \
  -H "Authorization: Bearer pk_live_your_api_key"

{
  "object": "list",
  "data": [
    {
      "id": "gemini-2.5-flash",
      "object": "model",
      "created": 1704056400,
      "owned_by": "google ai studio",
      "permission": [],
      "root": "gemini-2.5-flash",
      "parent": null
    },
    {
      "id": "gemini-2.0-flash",
      "object": "model",
      "created": 1704056400,
      "owned_by": "google ai studio",
      "permission": [],
      "root": "gemini-2.0-flash",
      "parent": null
    }
  ]
}

5. Embeddings API

Metin embedding'leri oluşturur. Semantik arama, benzerlik analizi ve RAG (Retrieval-Augmented Generation) sistemleri için kullanılır.

curl -X POST "https://api.pixellab.com.tr/api/v1/embeddings" \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-004",
    "input": "Merhaba dünya, bu bir test metnidir."
  }'

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0091, 0.0152, ... ]
    }
  ],
  "model": "text-embedding-004",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

6. Hata Kodları

API hatalarında aşağıdaki HTTP durum kodları ve hata formatı döner:

Hata Yanıt Formatı

{
  "error": {
    "message": "Hata açıklaması",
    "type": "error_type",
    "code": 400
  }
}

HTTP Durum Kodları

7. SDK Entegrasyonu

Bu API, OpenAI SDK'ları ile tam uyumludur. Sadece base URL'i değiştirerek mevcut kodunuzu kullanabilirsiniz.

Python (openai kütüphanesi)

from openai import OpenAI

# Client oluştur - sadece base_url ve api_key değiştirin
client = OpenAI(
    base_url="https://api.pixellab.com.tr/api/v1",
    api_key="pk_live_your_api_key"
)

# Normal OpenAI kullanımı gibi çağrı yapın
response = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[
        {"role": "system", "content": "Sen yardımcı bir asistansın."},
        {"role": "user", "content": "Python'da liste nasıl oluşturulur?"}
    ],
    temperature=0.7,
    max_tokens=500
)

print(response.choices[0].message.content)

Python (Streaming)

stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Kısa bir hikaye yaz"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

JavaScript / Node.js

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'https://api.pixellab.com.tr/api/v1',
    apiKey: 'pk_live_your_api_key'
});

async function chat() {
    const response = await client.chat.completions.create({
        model: 'gemini-2.0-flash',
        messages: [
            { role: 'user', content: 'Merhaba, bana yardım eder misin?' }
        ]
    });
    
    console.log(response.choices[0].message.content);
}

chat();

PHP (cURL)

<?php
$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.pixellab.com.tr/api/v1/chat/completions',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer pk_live_your_api_key',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'gemini-2.0-flash',
        'messages' => [
            ['role' => 'user', 'content' => 'Merhaba!']
        ]
    ])
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

echo $data['choices'][0]['message']['content'];

8. En İyi Uygulamalar

🔐 Güvenlik

• API anahtarınızı asla client-side kodda açık bırakmayın
• Her proje için ayrı API anahtarı kullanın
• Düzenli olarak API anahtarlarınızı rotate edin
• HTTPS üzerinden bağlantı kurun

⚡ Performans

• Uzun yanıtlar için streaming kullanın
• Gereksiz token kullanımından kaçının - prompt'larınızı optimize edin
• Sık kullanılan yanıtları cache'leyin
• max_tokens parametresini makul tutun

🔄 Hata Yönetimi

• 429 (Rate Limit) hatalarında exponential backoff uygulayın
• 5xx hatalarında otomatik retry mekanizması kullanın
• Timeout değerlerini uzun tutun (30-60 saniye)
• Hata loglarını kaydedin ve izleyin

💰 Maliyet Optimizasyonu

• Basit görevler için daha küçük modeller kullanın (örn: gemini-2.0-flash)
• System prompt'ları kısa ve öz tutun
• Gereksiz conversation history taşımaktan kaçının
• Kullanım istatistiklerinizi düzenli kontrol edin