Temel kılavuzlar
Güvenilir bir TokenLab entegrasyonu oluşturun
Maliyet, yeniden denemeler, API anahtarları ve istek kayıtlarını kontrol altında tutun
İyi bir entegrasyon; fiyat ve model seçimlerini görünür kılar, olağan ağ hatalarını atlatır ve bir API anahtarını asla tarayıcıda ifşa etmez. Aşağıdaki uygulamalar sohbet, görsel, video, ses ve diğer TokenLab API'leri genelinde geçerlidir.
Güncel verilere sahip modelleri seçin
Model isimleri, yetenekleri ve fiyatları değişebilir. Kodunuzda veya dokümantasyonunuzda kalıcı bir liste tutmak yerine Models API sayfasına veya model sayfalarına bakın.
Yeni bir kullanım durumu için:
- Modelleri, ürününüzün ihtiyaç duyduğu yeteneğe göre filtreleyin.
- Güncel TokenLab fiyatlarını karşılaştırın.
- Temsili kullanıcı istekleriyle küçük bir set üzerinde test edin.
- Model ID bilgisini her istekte açıkça belirtin.
Modelleri sessizce değiştirmeyin. Bir değişiklik; çıktı kalitesini, fiyatı, bağlam uzunluğunu (context length), mevcut araçları veya medya desteğini etkileyebilir.
Maliyete üst sınır koyun
Metin modelleri için çıktıyı, ürününüzün gerçekten kullanabileceği uzunlukla sınırlandırın. Parametre ismi API'ye ve modele göre değişir, bu nedenle max_tokens veya max_output_tokens göndermeden önce model sayfasını kontrol edin.
Daha kısa talimatlar otomatik olarak daha iyi değildir, ancak kopyalanmış bağlam ve tekrarlanan standart metinler (boilerplate) her zaman girdi token'larını artırır. Kararlı talimatları kısa tutun ve yalnızca bir sonraki yanıt için gereken geçmişi gönderin.
Görsel, video, müzik, 3D ve Worlds istekleri için maliyet genellikle çıktı sayısına, süreye, çözünürlüğe veya diğer medya seçeneklerine bağlıdır. API bir tahmin sağlayabildiğinde, kullanıcı pahalı bir üretimi onaylamadan önce güncel tahmini gösterin.
Uzun metin yanıtlarını akış (stream) ile alın
Akış (streaming), yanıtı geldiği anda gösterir ve kullanıcının yanıtın tamamlanmasını beklemesini önler. Bu, token maliyetini düşürmez.
İstemci kurulumu ve tamamlama kontrollerini içeren eksiksiz bir örnek için Akış (Streaming) bölümüne bakın.
Bağlantı kopmalarını tamamlanmamış bir yanıt olarak ele alın. Kısmi çıktıyı başarıyla tamamlanmış gibi sunmayın ve bunu yaparken ikinci bir yan etki yaratabilecek veya ücretlendirmeye yol açabilecek durumlarda isteği otomatik olarak tekrarlamayın.
Yalnızca güvenli olduğunda yeniden deneyin
429 yanıtlarını Retry-After veya retry_after değerlerinden sonra yeniden deneyin. Geçici 5xx yanıtları için kısa bir üstel geri çekilme (exponential backoff) uygundur. Kimlik doğrulama, doğrulama, bakiye ve bağlam uzunluğu hataları uygulama veya kullanıcı tarafında bir değişiklik gerektirir; aynı isteği tekrar göndermek bu hataları düzeltmeyecektir.
Retry-After değerine uyan ve yinelenen SDK yeniden denemelerini devre dışı bırakan sınırlı bir yeniden deneme örneği için Hız sınırları bölümüne bakın.
Bir yeniden deneme sınırı ve toplam süre sınırı belirleyin. Medya oluşturma işlemleri için döndürülen görev kimliğini (task ID) kaydedin. Retry safely with an idempotency key bölümünde listelenen istekler için bir Idempotency-Key gönderin; böylece zaman aşımı sonrası yapılan bir yeniden deneme, aynı isteği iki kez çalıştırmaz veya ücretlendirmez.
API anahtarlarını sunucuda tutun
Bir TokenLab API anahtarını asla tarayıcı JavaScript'ine, mobil uygulama paketine, herkese açık bir depoya veya istemci tarafından görülebilen bir günlüğe (log) gömmeyin.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=30.0,
max_retries=0,
)Geliştirme, üretim ve bağımsız uygulamalar için ayrı API anahtarları kullanın. Her anahtara yalnızca ihtiyaç duyduğu modelleri ve harcama limitini tanımlayın. İfşa edilmiş olabileceğinden şüpheleniyorsanız bir anahtarı derhal iptal edin.
Faydalı istek kayıtları tutun
Bir kullanıcı eylemini kullanım ve destek kayıtlarına bağlamanızı sağlayan tanımlayıcıları saklayın:
- API isteği için
request_id - Asenkron üretim için
task_id - Döndürüldüğünde
billing_transaction_id - Model ID ve uç nokta (endpoint)
- Kendi kullanıcı, proje veya iş kimliğiniz
API anahtarlarını, yönetim token'larını, tam özel istemleri (prompts), özel medyaları veya imzalı URL'leri günlüğe kaydetmeyin. Konsol ve Management API'deki kullanım kayıtları faturalandırılan tutarların kaynağıdır; yalnızca model yanıtı token sayıları nihai ücreti tam olarak tanımlamayabilir.
Asenkron çalışma için tasarlayın
Görsel, video, müzik, 3D ve Worlds API'leri sonuç hazır olmadan önce yanıt dönebilir. Görev kimliğini (task ID) kaydedin, GET /v1/tasks/{id} uç noktasını sorgulayın ve yalnızca completed veya failed durumunda durun. Başarısız bir durum sorgusu, üretimin kendisinin başarısız olduğu anlamına gelmez.
İptal, zaman aşımı ve yinelenen istek yönetimi için Asenkron işler ve sorgulama (polling) bölümüne bakın.
Yayına almadan önce
- Yayınlayacağınız tam model ve API formatı ile temsili istekler çalıştırın.
- Hem başarılı hem de yaygın hata yanıtlarını kontrol edin.
- Ürününüzde gösterilen fiyatın güncel TokenLab fiyatıyla eşleştiğini doğrulayın.
- Sayfa yenilemeleri, ağ zaman aşımları ve tekrarlanan tıklamaları güvenli hale getirin.
- Kullanıcı tarafından görülebilen bir sonucu, Request ID üzerinden geriye dönük izlenebilir kılın.