> ## 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.

# ✨ Skill Integrasi API TokenLab

> Pasang skill integrasi API TokenLab yang dipelihara dan bantu coding agent menemukan model, membaca detail model, serta pulih dari error API.

<Note>
  Halaman ini mendokumentasikan skill bersama `tokenlab-api-integration` yang dipelihara. Distribusi kanonis berada di [hedging8563/tokenlab-skills](https://github.com/hedging8563/tokenlab-skills), dan repository publik sengaja hanya menyimpan skill ini.
</Note>

<Note>
  Gunakan halaman ini untuk instalasi skill dan panduan workflow agent. Untuk setup endpoint tertentu, gunakan halaman SDK, client, atau API reference khusus alat tersebut.
</Note>

## Apa yang dilakukan skill ini

* Membuat contoh minimal yang dapat dijalankan untuk keluarga API TokenLab seperti chat, image, audio, video, translation, dan lainnya.
* Menggunakan `https://api.tokenlab.sh/v1` untuk client kompatibel OpenAI dan menjelaskan kapan berpindah ke route native Anthropic atau Gemini.
* Menemukan model lewat `/v1/models`, `/llms.txt`, dan daftar `recommended_for` alih-alih menebak dari daftar usang.
* Membaca detail model model sebelum mencoba ulang permintaan non-chat agar field yang tidak didukung tidak dibuang diam-diam.
* Menangani petunjuk error Agent-First seperti `did_you_mean`, `suggestions`, `retry_after`, dan `recommended_request`.

## Instalasi

<Note>
  Gunakan perintah instalasi kanonis non-interaktif:

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

  Ini memasang skill bersama `tokenlab-api-integration` dari repository TokenLab skills.

  Jika alat Anda tidak mendukung installer, salin `skills/tokenlab-api-integration/` dari repository ke direktori skills atau rules bersama milik alat Anda.
</Note>

### Perbarui instalasi yang ada

Jika Anda sudah menginstal skill sebelumnya, jalankan kembali perintah yang sama untuk memperbarui ke paket publik saat ini.

### Verifikasi instalasi

Tanyakan ke coding agent Anda:

```
Skills apa saja yang tersedia?
```

Jika `tokenlab-api-integration` terlihat, instalasi berhasil.

## Dapatkan API Key

<Steps>
  <Step title="Kunjungi TokenLab">
    Buka [tokenlab.sh](https://tokenlab.sh)
  </Step>

  <Step title="Masuk">
    Buat akun atau login
  </Step>

  <Step title="Dapatkan API Key">
    Buka [Dashboard → API Keys](https://tokenlab.sh/dashboard/api) dan buat key baru
  </Step>

  <Step title="Salin key">
    Key Anda diawali `sk-...`. Simpan dengan aman.
  </Step>
</Steps>

<Tip>
  Jangan tempel API keys ke prompt atau file sumber. Skill harus menanyakan variabel lingkungan yang digunakan dan menghasilkan kode yang membaca key dari variabel itu.
</Tip>

## Alur Agent yang disarankan

1. Mulai dari contoh kerja terkecil yang sesuai dengan bahasa dan keluarga API yang diminta pengguna.
2. Saat pilihan model terbuka, panggil `/v1/models` atau `https://api.tokenlab.sh/llms.txt` sebelum meng-hardcode model.
3. Untuk pekerjaan non-chat, panggil `/v1/models?recommended_for=<scene>` dengan `<scene>` berupa `image`, `video`, `music`, `3d`, `tts`, `stt`, `embedding`, `rerank`, atau `translation`.
4. Sebelum mengubah permintaan non-chat yang gagal, baca `/v1/models/:model` dan selaraskan dengan `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, dan `recommended_request`.
5. Jika API mengembalikan error Agent-First, gunakan field terstruktur untuk memperbaiki permintaan dan coba ulang hanya jika error retryable.

## Contoh chat minimal

Contoh ini memakai OpenAI Python SDK dengan base URL TokenLab:

```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)
```

Jalankan dengan:

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

## Penemuan model dan detail model

Utamakan penemuan live daripada daftar bawaan yang usang:

```bash theme={null}
# Ringkasan API yang dapat dibaca mesin
curl https://api.tokenlab.sh/llms.txt

# Daftar model
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"

# Daftar pendek non-chat berperingkat
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"

# Baca detail model satu model sebelum mencoba ulang permintaan non-chat
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# Detail khusus harga
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"
```

## Petunjuk routing native

Jalur kompatibel OpenAI `/v1` adalah default untuk contoh umum chat, Responses, image, embedding, audio, dan rerank. Gunakan route native Anthropic atau Gemini hanya ketika permintaan membutuhkan perilaku khusus provider atau TokenLab mengembalikan `X-TokenLab-Native-Endpoint` sebagai petunjuk optimasi.

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

## Pemulihan error Agent-First

Error menyertakan field yang dapat diparse coding agent tanpa mengorek dokumentasi:

| Error                                    | Field berguna                                                                                                                                    | Tindakan agent                                                                                   |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| Nama model salah                         | `did_you_mean`, `suggestions`, `hint`                                                                                                            | Coba ulang dengan model yang diperbaiki atau satu alternatif yang disarankan                     |
| Saldo tidak cukup                        | `balance_usd`, `estimated_cost_usd`, `suggestions`                                                                                               | Minta persetujuan atau pindah ke model yang lebih terjangkau                                     |
| Batas laju atau sementara tidak tersedia | `retryable`, `retry_after`, `alternatives`                                                                                                       | Tunggu, coba ulang, atau pilih alternatif yang tercantum                                         |
| Kontrak non-chat tidak cocok             | `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request` | Bangun ulang permintaan dari detail model dan return a clear error pada field yang mengubah niat |

## Keluarga API yang didukung

| Keluarga                 | Path utama                                                               |
| ------------------------ | ------------------------------------------------------------------------ |
| Chat dan Responses       | `/v1/chat/completions`, `/v1/responses`                                  |
| Claude-native messages   | `/v1/messages`                                                           |
| Permintaan Gemini-native | `/v1beta/models/{model}:generateContent`                                 |
| Gambar                   | `/v1/images/generations`, `/v1/images/edits`                             |
| Video                    | `/v1/videos/generations`                                                 |
| Musik                    | `/v1/music/generations`                                                  |
| Worlds                   | `/v1/worlds/generations` plus endpoint status world dan media asset      |
| 3D                       | `/v1/3d/generations`                                                     |
| Audio                    | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| Realtime                 | `/v1/realtime?model={model}`                                             |
| Embeddings dan rerank    | `/v1/embeddings`, `/v1/rerank`                                           |
| Terjemahan teks          | `/v1/translations`                                                       |

## Praktik terbaik

<CardGroup cols={2}>
  <Card title="Keamanan API Key" icon="shield">
    Gunakan variabel lingkungan dan panggilan server-side. Jangan pernah mengekspos keys di kode frontend.
  </Card>

  <Card title="Kontrak dulu untuk non-chat" icon="file-code">
    Baca `/v1/models?recommended_for=...` dan `/v1/models/:model` sebelum mencoba ulang permintaan image, video, music, 3D, translation, audio, embedding, atau rerank.
  </Card>

  <Card title="Contoh berjalan terkecil" icon="terminal">
    Buat satu panggilan yang berfungsi sebelum menambahkan abstraksi, antrean, atau alur UI.
  </Card>

  <Card title="Gunakan petunjuk terstruktur" icon="rotate-cw">
    Parse `did_you_mean`, `retry_after`, `alternatives`, dan `recommended_request` sebelum mengubah kode.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Skill tidak terpicu otomatis?">
    Sebut “TokenLab” atau “TokenLab API” dalam permintaan, misalnya: `Gunakan TokenLab untuk menambahkan pembuatan gambar ke app Node.js saya`.
  </Accordion>

  <Accordion title="Coding agent apa yang didukung?">
    Coding agent apa pun yang mendukung direktori skill atau rules bersama dapat menggunakan folder ini. Installer `skills` menangani agent yang didukung secara otomatis.
  </Accordion>

  <Accordion title="Bagaimana memperbarui skill?">
    Jalankan ulang perintah instalasi. Perintah ini menyegarkan salinan lokal dari repository publik kanonis.

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

## Sumber daya

<CardGroup cols={2}>
  <Card title="Agent-First API" icon="robot" href="/id/guides/agent-first-api">
    Petunjuk error terstruktur dan perilaku pemulihan
  </Card>

  <Card title="Dokumentasi API" icon="book" href="https://docs.tokenlab.sh">
    Setup per endpoint dan API Reference
  </Card>

  <Card title="Model" icon="sparkles" href="https://tokenlab.sh/id/models">
    Jelajahi model yang tersedia
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    Ringkasan API yang dapat dibaca mesin untuk agents
  </Card>
</CardGroup>

<Info>
  Ada pertanyaan? Gunakan [GitHub Issues](https://github.com/hedging8563/tokenlab-skills/issues) atau hubungi [support@tokenlab.sh](mailto:support@tokenlab.sh).
</Info>