✨ Ajan-Öncelikli API

Genel Bakış

TokenLab’nın Agent-First API’si, hata yanıtlarını AI ajanlarının hemen ayrıştırıp harekete geçebileceği yapılandırılmış ipuçlarıyla zenginleştirir — web aramaları yok, doküman bakışları yok, tahmin yürütme yok. OpenAI uyumlu Chat Completions ve Responses gateway hataları, error nesnesinde did_you_mean, suggestions, hint, retryable ve retry_after gibi isteğe bağlı alanlar içerebilir. Anthropic Messages ve Gemini yerel hata şekillerini korur ve bu uzantıları vaat etmez.

Hata İpucu Alanları

OpenAI uyumlu gateway hatalarında tüm ipucu alanları error nesnesi içinde isteğe bağlı uzantılardır:

Alan	Tür	Açıklama
`did_you_mean`	`string`	En yakın eşleşen model adı
`suggestions`	`array`	Meta veriye sahip önerilen modeller
`alternatives`	`array`	Mevcut alternatif modeller
`hint`	`string`	İnsan/ajan tarafından okunabilir sonraki adım yönlendirmesi
`retryable`	`boolean`	Aynı isteğin yeniden denenmesinin başarılı olma olasılığı
`retry_after`	`number`	Yeniden denemeden önce beklenmesi gereken saniye
`balance_usd`	`number`	Hesap bakiyesi (USD cinsinden)
`estimated_cost_usd`	`number`	Başarısız olan isteğin tahmini maliyeti (USD)

Hata Kodu Örnekleri

model_not_found (400)

Bir model adı aktif hiçbir modelle eşleşmediğinde:

{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.4",
    "suggestions": [
      {"id": "gpt-5.4"},
      {"id": "gpt-5-mini"},
      {"id": "claude-sonnet-4-6"}
    ],
    "hint": "Did you mean 'gpt-5.4'? Use GET https://api.tokenlab.sh/v1/models to list all available models."
  }
}

did_you_mean çözümlemesi şu yöntemleri kullanır:

Statik takma ad eşlemesi (prodüksiyon hata verilerinden)
Normalleştirilmiş string eşlemesi (tireleri kaldırır, büyük/küçük harf duyarsız)
Düzenleme uzaklığı eşlemesi (eşik ≤ 3)

Genel erişim (public) rotaları, gizli, ertelenmiş veya herkese açık olmayan modeller için ayrı hata kodları açığa çıkarmaz. Kullanılamayan genel modelleri bir yanlış yazım gibi değerlendirin: did_you_mean, suggestions ve hint alanlarını inceleyin ve sonra desteklenen bir genel model ile yeniden deneyin.

insufficient_balance (402)

Hesap bakiyesi tahmini maliyet için yetersiz olduğunda:

{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5-mini"},
      {"id": "deepseek-v3-2"}
    ],
    "hint": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200. Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

suggestions, ajanların geçiş yapabileceği tahmini maliyetten daha ucuz modelleri içerir.

all_channels_failed (503)

Bir model için tüm üst akış kanalları kullanılamaz olduğunda:

{
  "error": {
    "message": "Model claude-opus-4-6 temporarily unavailable",
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-6", "status": "available", "tags": []},
      {"id": "gpt-5-mini", "status": "available", "tags": []}
    ],
    "hint": "All channels for 'claude-opus-4-6' are temporarily unavailable. Retry in 30s or try an alternative model."
  }
}

retryable, neden no_channels ise false olur (bu model için yapılandırılmış kanal yok). Yalnızca devre kesici atlamaları veya kota tükenmesi gibi geçici hatalar için true olur.

rate_limit_exceeded (429)

{
  "error": {
    "message": "Rate limit: 1000 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
  }
}

retry_after değeri, gerçek hız limiti pencere sıfırlama zamanından hesaplanır.

OpenAI-uyumlu uç noktalar, rate_limit_exceeded, upstream_error ve all_channels_failed gibi TokenLab’nın kararlı genel hata türlerini kullanır. Anthropic-uyumlu ve Gemini-uyumlu uç noktalar kendi yerel yanıt biçimlerini kullanır.

context_length_exceeded (400)

Girdi modelin bağlam penceresini aştığında (üst akış hatası, ipuçları ile zenginleştirilmiş):

{
  "error": {
    "message": "This model's maximum context length is 128000 tokens...",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "retryable": false,
    "suggestions": [
      {"id": "gemini-2.5-pro"},
      {"id": "claude-sonnet-4-6"}
    ],
    "hint": "Reduce your input or switch to a model with a larger context window."
  }
}

Yerel Uç Nokta Keşfi

Yerel protokol kullanılabilirliğini model ya da sağlayıcı adından veya Chat yanıt başlıklarından çıkarmayın. Yerel uç nokta seçmeden önce GET /v1/models/{model} isteğini okuyun ve yalnızca model ayrıntılarında ilan edilen ve aynı protokole sahip bir route tarafından desteklenen istek biçimini kullanın. Okunacak alan tokenlab.accepted_request_formats değeridir.

İstek biçimi	Uç nokta
Chat Completions	`/v1/chat/completions`
Responses	`/v1/responses`
Messages	`/v1/messages`
Gemini	`/v1beta/models/{model}:generateContent`

İlan edilen istek biçimi uç noktanın kullanılabilirliğini belirler; tek tek alan ve araç desteği upstream’e bağlıdır.

/v1/models İyileştirmeleri

/v1/models artık ajanların görüntü, video, müzik, 3B, TTS, STT, embedding, rerank veya çeviri uç noktalarını çağırmadan önce kullanabileceği sohbet dışı öneri meta verilerini taşır.

{
  "id": "gemini-2.5-flash-image",
  "tokenlab": {
    "category": "image",
    "pricing_unit": "per_request",
    "agent_preferences": {
      "image": {
        "preferred_rank": 1,
        "success_rate_24h": 0.98,
        "sample_count_24h": 423,
        "status": "ready",
        "updated_at": "2026-03-28T12:00:00.000Z",
        "basis": {
          "source": "recent_activity_24h"
        }
      }
    }
  }
}

Alan	Değerler	Açıklama
`category`	`chat`, `image`, `video`, `audio`, `tts`, `stt`, `3d`, `embedding`, `rerank`	Model türü
`pricing_unit`	`per_token`, `per_image`, `per_second`, `per_request`	Modelin faturalama yöntemi
`cache_pricing`	object or `null`	Yalnızca modelin kendi upstream prompt cache fiyatları varsa döner.
`agent_preferences.<scene>`	object	Yalnızca `GET /v1/models?recommended_for=<scene>` ile dönen sohbet dışı öneri anlık görüntüsü

recommended_for mevcutsa agent_preferences, önbelleğe alınmış 24 saatlik başarı oranı anlık görüntüsünden türetilir:

Pencere: 24 saat
Anlık görüntü önbelleği: stale-while-revalidate
status = "ready" modelin sıralamaya katılmak için yeterli güncel örneğe sahip olduğunu gösterir
status = "insufficient_samples" model görünür kalır ancak puanlanmış modellerin önüne alınmaz

Kategori Filtreleme

GET https://api.tokenlab.sh/v1/models?category=chat          # Chat modelleri yalnızca
GET https://api.tokenlab.sh/v1/models?category=image         # Görüntü üretim modelleri
GET https://api.tokenlab.sh/v1/models?tag=coding&category=chat  # Kodlama-optimze chat modelleri

Öneri Keşfi

Sohbet dışı iş akışları için ajanlar önce geçerli önerilen kısa listeyi almalıdır:

GET https://api.tokenlab.sh/v1/models?recommended_for=image
GET https://api.tokenlab.sh/v1/models?recommended_for=translation
GET https://api.tokenlab.sh/v1/models?category=tts&recommended_for=tts

Geçerli recommended_for değerleri şunlardır:

image
video
music
3d
tts
stt
embedding
rerank
translation

Hem category hem de recommended_for mevcutsa, bunların tam olarak eşleşmesi gerekir. Önerilen ajan akışı:

GET /v1/models?recommended_for=<scene>
İlk agent_preferences.<scene>.status == "ready" olan modeli seçin
Uç noktayı açıkça model=<selected> ile çağırın
Yalnızca geçici hatalarda, bir sonraki ready model ile yeniden deneyin

llms.txt

Makine tarafından okunabilir bir API genel bakışı şu adreste mevcuttur:

GET https://api.tokenlab.sh/llms.txt

İçerir:

Çalışan bir örnekle ilk çağrı şablonu
Yaygın model adları (kullanım verilerinden dinamik olarak oluşturulur)
Tüm 12 API uç noktası
Model keşfi için filtre parametreleri
Hata işleme rehberi

llms.txt dosyasını ilk API çağrılarından önce okuyan AI ajanları tipik olarak ilk denemede başarılı olabilir.

Ajan Kodunda Kullanım

Python (OpenAI SDK)

from openai import OpenAI, BadRequestError

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.tokenlab.sh/v1"
)

def smart_chat(messages, model="gpt-4o"):
    try:
        return client.chat.completions.create(
            model=model, messages=messages
        )
    except BadRequestError as e:
        error = e.body.get("error", {}) if isinstance(e.body, dict) else {}
        # Use did_you_mean for auto-correction
        if error.get("code") == "model_not_found" and error.get("did_you_mean"):
            return client.chat.completions.create(
                model=error["did_you_mean"], messages=messages
            )
        raise

JavaScript (OpenAI SDK)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

async function smartChat(messages, model = 'gpt-4o') {
  try {
    return await client.chat.completions.create({ model, messages });
  } catch (error) {
    const err = error?.error;
    if (err?.code === 'model_not_found' && err?.did_you_mean) {
      return client.chat.completions.create({
        model: err.did_you_mean, messages
      });
    }
    throw error;
  }
}

Tasarım İlkeleri

Hızlı başarısızlık, bilgilendirici hata

Hatalar, bir ajanın kendi kendini düzeltmesi için ihtiyaç duyduğu tüm verilerle hemen döner.

Otomatik yönlendirme yok

API asla sessizce farklı bir model ikamesi yapmaz. Kararı ajan verir.

Veri odaklı öneriler

Tüm öneriler sert kodlanmış listelerden değil, prodüksiyon verilerinden gelir.

Geriye uyumlu

Tüm ipucu alanları isteğe bağlıdır. Mevcut istemciler hiçbir fark görmez.

Başlarken

Temel kılavuzlar

Medya kılavuzları

✨ Ajan-Öncelikli API

Genel Bakış

Hata İpucu Alanları

Hata Kodu Örnekleri

model_not_found (400)

insufficient_balance (402)

all_channels_failed (503)

rate_limit_exceeded (429)

context_length_exceeded (400)

Yerel Uç Nokta Keşfi

/v1/models İyileştirmeleri

Kategori Filtreleme

Öneri Keşfi

llms.txt

Ajan Kodunda Kullanım

Python (OpenAI SDK)

JavaScript (OpenAI SDK)

Tasarım İlkeleri

Hızlı başarısızlık, bilgilendirici hata

Otomatik yönlendirme yok

Veri odaklı öneriler

Geriye uyumlu

​Genel Bakış

​Hata İpucu Alanları

​Hata Kodu Örnekleri

​model_not_found (400)

​insufficient_balance (402)

​all_channels_failed (503)

​rate_limit_exceeded (429)

​context_length_exceeded (400)

​Yerel Uç Nokta Keşfi

​/v1/models İyileştirmeleri

​Kategori Filtreleme

​Öneri Keşfi

​llms.txt

​Ajan Kodunda Kullanım

​Python (OpenAI SDK)

​JavaScript (OpenAI SDK)

​Tasarım İlkeleri

Hızlı başarısızlık, bilgilendirici hata

Otomatik yönlendirme yok

Veri odaklı öneriler

Geriye uyumlu

Genel Bakış

Hata İpucu Alanları

Hata Kodu Örnekleri

model_not_found (400)

insufficient_balance (402)

all_channels_failed (503)

rate_limit_exceeded (429)

context_length_exceeded (400)

Yerel Uç Nokta Keşfi

/v1/models İyileştirmeleri

Kategori Filtreleme

Öneri Keşfi

llms.txt

Ajan Kodunda Kullanım

Python (OpenAI SDK)

JavaScript (OpenAI SDK)

Tasarım İlkeleri