> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# ✨ TokenLab API Entegrasyon Skill’i

> Bakımı sürdürülen TokenLab API entegrasyon skill’ini kurun ve coding agent’lara model keşfi, model details okuma ve API hatalarından toparlanma yolunu öğretin.

<Note>
  Bu sayfa bakımı sürdürülen ortak `tokenlab-api-integration` skill’ini açıklar. Kanonik dağıtım [hedging8563/tokenlab-skills](https://github.com/hedging8563/tokenlab-skills) içindedir; public repository bilinçli olarak yalnızca bu skill’i tutar.
</Note>

<Note>
  Bu sayfayı skill kurulumu ve agent iş akışı rehberi için kullanın. Endpoint özelindeki kurulumlar için ilgili SDK, client veya API reference sayfasını kullanın.
</Note>

## Skill ne yapar

* TokenLab chat, image, audio, video, translation ve diğer API aileleri için minimum çalıştırılabilir örnekler üretir.
* OpenAI uyumlu client’lar için `https://api.tokenlab.sh/v1` kullanır ve native Anthropic veya Gemini route’larına ne zaman geçileceğini açıklar.
* Eskimiş listelerden tahmin etmek yerine `/v1/models`, `/llms.txt` ve `recommended_for` kısa listeleriyle modelleri keşfeder.
* Non-chat istekleri tekrar denemeden önce modelin model details bilgisini okur; desteklenmeyen alanlar sessizce atılmaz.
* `did_you_mean`, `suggestions`, `retry_after`, `recommended_request` gibi Agent-First hata ipuçlarını işler.

## Kurulum

<Note>
  Kanonik etkileşimsiz kurulum komutunu kullanın:

  ```bash theme={null}
  npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
  ```

  Bu komut TokenLab skills repository’den ortak `tokenlab-api-integration` skill’ini kurar.

  Aracınız installer desteklemiyorsa repository içindeki `skills/tokenlab-api-integration/` klasörünü aracınızın ortak skills veya rules dizinine kopyalayın.
</Note>

### Mevcut kurulumları güncelleme

Skill’i TokenLab repository temizliğinden önce kurduysanız aynı komutu yeniden çalıştırın. Güncel public paket daha küçüktür ve üretilmiş yerel arama script’lerine artık bağlı değildir.

### Kurulumu doğrulama

Coding agent’ınıza sorun:

```
Hangi skills kullanılabilir?
```

`tokenlab-api-integration` görünüyorsa kurulum başarılıdır.

## API Key alma

<Steps>
  <Step title="TokenLab’i ziyaret edin">
    [tokenlab.sh](https://tokenlab.sh) adresine gidin
  </Step>

  <Step title="Giriş yapın">
    Hesap oluşturun veya giriş yapın
  </Step>

  <Step title="API Key alın">
    [Dashboard → API Keys](https://tokenlab.sh/dashboard/api) bölümünü açıp yeni bir key oluşturun
  </Step>

  <Step title="key’i kopyalayın">
    key `sk-...` ile başlar. Güvenli saklayın.
  </Step>
</Steps>

<Tip>
  API keys değerlerini prompt’lara veya kaynak dosyalara yapıştırmayın. Skill hangi ortam değişkeninin kullanılacağını sormalı ve key’i o değişkenden okuyan kod üretmelidir.
</Tip>

## Önerilen Agent iş akışı

1. Kullanıcının istediği dil ve API ailesiyle eşleşen en küçük çalışan örnekle başlayın.
2. Model seçimi açıksa bir modeli hard-code etmeden önce `/v1/models` veya `https://api.tokenlab.sh/llms.txt` çağırın.
3. Non-chat işlerde `/v1/models?recommended_for=<scene>` çağırın; `<scene>` `image`, `video`, `music`, `3d`, `tts`, `stt`, `embedding`, `rerank` veya `translation` olabilir.
4. Başarısız non-chat isteği değiştirmeden önce `/v1/models/:model` okuyun ve `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request` ile hizalayın.
5. API Agent-First hata döndürürse isteği yapılandırılmış alanlarla düzeltin ve yalnızca hata retryable ise yeniden deneyin.

## Minimum chat örneği

Bu örnek OpenAI Python SDK ile TokenLab base URL kullanır:

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)

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

Şununla çalıştırın:

```bash theme={null}
pip install openai
export TOKENLAB_API_KEY="sk-your-api-key"
python app.py
```

## Model keşfi ve model details’lar

Eskimiş paket listeleri yerine canlı keşfi tercih edin:

```bash theme={null}
# Makine tarafından okunabilir API özeti
curl https://api.tokenlab.sh/llms.txt

# Modelleri listele
curl "https://api.tokenlab.sh/v1/models" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?category=image" -H "Authorization: Bearer sk-KEY"

# Sıralı non-chat kısa listeleri
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=translation" -H "Authorization: Bearer sk-KEY"

# Non-chat isteği tekrar denemeden önce tek modelin model details bilgisini oku
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# Yalnızca fiyat ayrıntısı
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"
```

## Native routing ipuçları

Yaygın chat, Responses, image, embedding, audio ve rerank örnekleri için OpenAI uyumlu `/v1` varsayılan yoldur. Native Anthropic veya Gemini route’larını yalnızca istek sağlayıcıya özel davranış gerektirdiğinde ya da TokenLab `X-TokenLab-Native-Endpoint` optimizasyon ipucu döndürdüğünde kullanın.

```
X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages
```

## Agent-First hata toparlama

Hatalar, coding agent’ların dokümanı kazımadan ayrıştırabileceği alanlar içerir:

| Hata                                 | Yararlı alanlar                                                                                                                                  | Agent eylemi                                                                                             |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| Yanlış model adı                     | `did_you_mean`, `suggestions`, `hint`                                                                                                            | Düzeltilmiş modelle veya önerilen bir alternatifle yeniden deneyin                                       |
| Yetersiz bakiye                      | `balance_usd`, `estimated_cost_usd`, `suggestions`                                                                                               | Onay isteyin veya uygun maliyetli bir modele geçin                                                       |
| Hız sınırı veya geçici kullanılamama | `retryable`, `retry_after`, `alternatives`                                                                                                       | Bekleyin, yeniden deneyin veya listelenen bir alternatifi seçin                                          |
| Sohbet dışı contract uyuşmazlığı     | `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request` | İsteği model details üzerinden yeniden kurun; niyeti değiştiren alanlarda return a clear error uygulayın |

## Desteklenen API aileleri

| Aile                   | Birincil yol                                                             |
| ---------------------- | ------------------------------------------------------------------------ |
| Chat ve Responses      | `/v1/chat/completions`, `/v1/responses`                                  |
| Claude-native messages | `/v1/messages`                                                           |
| Gemini-native istekler | `/v1beta/models/{model}:generateContent`                                 |
| Görseller              | `/v1/images/generations`, `/v1/images/edits`                             |
| Video                  | `/v1/videos/generations`                                                 |
| Müzik                  | `/v1/music/generations`                                                  |
| Worlds                 | `/v1/worlds/generations` ve world status ile media asset endpoint’leri   |
| 3D                     | `/v1/3d/generations`                                                     |
| Ses                    | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| Realtime               | `/v1/realtime?model={model}`                                             |
| Embeddings ve rerank   | `/v1/embeddings`, `/v1/rerank`                                           |
| Metin çevirisi         | `/v1/translations`                                                       |

## En iyi uygulamalar

<CardGroup cols={2}>
  <Card title="API Key güvenliği" icon="shield">
    Ortam değişkenleri ve server-side çağrılar kullanın. Keys değerlerini frontend kodunda asla göstermeyin.
  </Card>

  <Card title="Non-chat için önce contract" icon="file-code">
    Image, video, music, 3D, translation, audio, embedding veya rerank isteklerini tekrar denemeden önce `/v1/models?recommended_for=...` ve `/v1/models/:model` okuyun.
  </Card>

  <Card title="En küçük çalışır örnek" icon="terminal">
    Soyutlama, queue veya UI akışı eklemeden önce çalışan tek bir çağrı üretin.
  </Card>

  <Card title="Yapılandırılmış ipuçlarını kullan" icon="rotate-cw">
    Kodu değiştirmeden önce `did_you_mean`, `retry_after`, `alternatives` ve `recommended_request` alanlarını ayrıştırın.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Skill otomatik tetiklenmiyor mu?">
    İstekte “TokenLab” veya “TokenLab API” ifadesini kullanın. Örnek: `Node.js uygulamama görsel üretimi eklemek için TokenLab kullan`.
  </Accordion>

  <Accordion title="Hangi coding agent’lar destekleniyor?">
    Ortak skill veya rules dizinlerini destekleyen her coding agent bu klasörü kullanabilir. `skills` installer desteklenen agent’ları otomatik işler.
  </Accordion>

  <Accordion title="Skill nasıl güncellenir?">
    Kurulum komutunu yeniden çalıştırın. Yerel kopyayı kanonik public repository’den yeniler.

    ```bash theme={null}
    npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
    ```
  </Accordion>
</AccordionGroup>

## Kaynaklar

<CardGroup cols={2}>
  <Card title="Agent-First API" icon="robot" href="/tr/guides/agent-first-api">
    Yapılandırılmış hata ipuçları ve toparlama davranışı
  </Card>

  <Card title="API dokümantasyonu" icon="book" href="https://docs.tokenlab.sh">
    Endpoint özelinde kurulum ve API Reference
  </Card>

  <Card title="Modeller" icon="sparkles" href="https://tokenlab.sh/tr/models">
    Kullanılabilir modelleri inceleyin
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    Agents için makine tarafından okunabilir API özeti
  </Card>
</CardGroup>

<Info>
  Sorular için [GitHub Issues](https://github.com/hedging8563/tokenlab-skills/issues) kullanın veya [support@tokenlab.sh](mailto:support@tokenlab.sh) ile iletişime geçin.
</Info>