AI Model REST API Dokümantasyonu

AI Model REST API Dokümantasyonu, yapay zeka modellerini entegre etmek isteyen geliştiriciler ve kurumlar için kapsamlı bir rehber sunar. Bu API, metin tabanlı tahminler, içerik üretimi ve veri analizi gibi görevleri kolayca gerçekleştirme imkanı sağlar. Standart REST mimarisi üzerine kurulu olan bu servis, JSON formatında veri alışverişi yapar ve HTTPS protokolüyle güvenli iletişim kurar. Kurumsal ortamlar için ölçeklenebilirlik ve güvenilirlik ön plandadır; dakikada binlerce istek işleyebilir ve %99,9 uptime garantisi verir. Bu dokümantasyon, API’yi hızlıca devreye alma adımlarını, endpoint detaylarını ve pratik örnekleri içerir. Başlamak için bir API anahtarı edinin ve isteklerinizi yapılandırın; böylece AI gücünü uygulamalarınıza entegre edebilirsiniz.

API Yapısı ve Kimlik Doğrulama

API erişimi, güvenli bir kimlik doğrulama mekanizmasıyla sağlanır. Tüm istekler, HTTP başlıklarında Bearer token formatında API anahtarı taşır. Bu yaklaşım, yetkisiz erişimleri engeller ve kurumsal veri güvenliğini korur. Ana base URL https://api.aimodel.example.com/v1 şeklindedir; tüm endpoint’ler bu kök yolun altındadır. İstekler POST metoduyla yapılırken, yanıtlar JSON yapısındadır ve rate limiting uygulanır: Dakikada 100 istek sınırı vardır, aşım durumunda 429 hatası döner.

API Anahtarı Oluşturma ve Yönetimi

API anahtarınızı platform panelinden oluşturun. Giriş yaptıktan sonra “API Keys” bölümüne gidin, yeni anahtar butonuna tıklayın ve kullanım haklarını tanımlayın (örneğin, sadece tahmin endpoint’i). Anahtar 64 karakterlik bir string’dir, örneğin “sk-abc123def456…”. Bu anahtarı saklayın ve asla kodunuzda hardcoded etmeyin; ortam değişkenleri kullanın. Anahtar iptal edilebilir veya yenilenebilir; eski anahtarlar 24 saat sonra devre dışı kalır. Pratikte, Node.js’te process.env.API_KEY ile erişin. Bu yöntem, geliştirme ve üretim ortamlarında tutarlılık sağlar ve güvenlik açıklarını minimize eder. Anahtarınızı düzenli olarak rotasyon yapın, örneğin aylık bazda.

İstek Başlıkları ve Formatı

Her istekte şu başlıkları ekleyin: Authorization: Bearer YOUR_API_KEY, Content-Type: application/json ve User-Agent: YourApp/1.0. Örnek bir istek curl ile şöyle yapılır: curl -X POST https://api.aimodel.example.com/v1/predict -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" -d '{"prompt": "Merhaba dünya"}'. Yanıtlar 200 OK ile döner, hata durumlarında status code ve detaylı mesaj içerir. Bu standartlar, entegrasyonu hızlandırır ve debug işlemini kolaylaştırır. Başlıkları doğru ayarlamak, %90 oranında yaygın hataları önler.

Kimlik doğrulama tamamlandıktan sonra, endpoint’lere özgü parametreleri inceleyin. Rate limit bilgisini X-RateLimit-Remaining başlığından takip edin ve exponential backoff stratejisi uygulayın.

Ana Endpoint’ler ve Kullanım Örnekleri

API’nin temel endpoint’leri, AI modelinin çekirdek yeteneklerini kapsar. En sık kullanılanlar tahmin ve üretkenlik odaklıdır. Her endpoint, input JSON’u alır ve structured output verir. Parametreler zorunlu ve opsiyonel olarak ayrılır; varsayılan değerler optimize edilmiştir. Örnek kod snippet’leri, Python requests kütüphanesiyle verilir ki hızlı prototipleme yapılabilsin.

Tahmin Endpoint’i (/predict)

Bu endpoint, metin girişine dayalı sınıflandırma veya sentiment analizi yapar. POST /v1/predict‘e şu JSON’u gönderin: {"text": "Ürün kalitesi mükemmel.", "model": "sentiment-v2"}. Yanıt: {"prediction": "positive", "confidence": 0.92}. Opsiyonel parametreler: max_tokens: 512, temperature: 0.7. Python örneği: import requests; response = requests.post(url, headers=headers, json=payload); print(response.json()). Bu endpoint, müşteri yorumu analizinde idealdir; batch moduyla birden fazla text işleyebilirsiniz, örneğin liste halinde input verin. Güvenilirlik için timeout 30 saniye ayarlayın.

İçerik Üretim Endpoint’i (/generate)

Metin üretimi için POST /v1/generate kullanın. Input: {"prompt": "Yapay zeka hakkında bir paragraf yaz.", "max_length": 200, "top_p": 0.9}. Çıktı: {"generated_text": "Yapay zeka, ...", "tokens_used": 150}. Temperature parametresi yaratıcılığı kontrol eder (0.2 deterministik, 1.0 rastgele). Örnek kullanım: Blog içerik otomasyonu. Döngüde birden fazla varyasyon üretin ve en iyisini seçin. Maliyet optimizasyonu için stop_sequences ekleyin, örneğin [“\n\n”]. Bu endpoint, pazarlama metinleri için vazgeçilmezdir ve streaming desteğiyle gerçek zamanlı yanıt alınabilir.

Endpoint’leri test etmek için Postman gibi araçlar önerilir. Her çağrıda usage bilgisini loglayın ki faturalama takibi kolaylaşsın.

Hata Yönetimi ve En İyi Uygulamalar

Hata kodları standart HTTP status’lere uyar: 400 Bad Request (geçersiz JSON), 401 Unauthorized, 500 Internal Server Error. Yanıtlarda {"error": "Detaylı mesaj", "code": "INVALID_PROMPT"} döner. Retry mantığı kurun: 5xx hatalarda 2^n saniye bekleyin. Loglama ile sorunları teşhis edin.

Yaygın Hatalar ve Çözümleri

401 hatası için anahtarı kontrol edin; 429 için bekleyin. Prompt çok uzunsa 413 döner, metni kısaltın. Örnek çözüm: Try-catch bloğuyla sarın ve fallback model kullanın. Bu yaklaşımlar, üretimde kesintisizliği sağlar. Ayrıca, input validation client tarafında yapın ki gereksiz çağrılar önlensin.

En iyi uygulamalar arasında caching (Redis ile yanıtları saklayın), monitoring (Prometheus entegrasyonu) ve versioning (/v1, /v2) yer alır. Ölçek için async çağrılar tercih edin. Bu stratejilerle API’nizi kurumsal seviyeye taşıyın.

Bu dokümantasyonla AI Model REST API’sini etkin kullanmaya hazırsınız. Pratik örnekleri kendi projelerinizde uyarlayın, parametreleri ince ayarlayın ve performansı izleyin. Düzenli güncellemeleri takip ederek en yeni özellikleri entegre edin; böylece rekabet avantajı kazanın.