✨ Agent-First API

Ikhtisar

Agent-First API TokenLab memperkaya respons kesalahan dengan petunjuk terstruktur yang dapat diurai dan ditindaklanjuti langsung oleh agen AI — tanpa pencarian web, tanpa mencari dokumentasi, tanpa tebak-tebakan. Error gateway Chat Completions dan Responses yang kompatibel dengan OpenAI dapat menyertakan field opsional seperti did_you_mean, suggestions, hint, retryable, dan retry_after dalam objek error. Endpoint Anthropic Messages dan Gemini mempertahankan bentuk error native dan tidak menjanjikan ekstensi ini.

Bidang Petunjuk Kesalahan

Untuk error gateway yang kompatibel dengan OpenAI, semua field petunjuk adalah ekstensi opsional di dalam objek error:

Bidang	Tipe	Deskripsi
`did_you_mean`	`string`	Nama model yang paling mirip
`suggestions`	`array`	Model yang direkomendasikan beserta metadata
`alternatives`	`array`	Model alternatif yang saat ini tersedia
`hint`	`string`	Panduan langkah selanjutnya yang dapat dibaca manusia/agen
`retryable`	`boolean`	Apakah mengulang permintaan yang sama mungkin berhasil
`retry_after`	`number`	Detik yang harus ditunggu sebelum mengulang
`balance_usd`	`number`	Saldo akun saat ini dalam USD
`estimated_cost_usd`	`number`	Estimasi biaya dari permintaan yang gagal

Contoh Kode Kesalahan

model_not_found (400)

Ketika nama model tidak cocok dengan model aktif manapun:

{
  "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."
  }
}

Resolusi did_you_mean menggunakan:

Pemetaan alias statis (dari data kesalahan produksi)
Pencocokan string ternormalisasi (menghapus tanda hubung, tidak sensitif huruf)
Pencocokan jarak edit (ambang ≤ 3)

Rute publik tidak mengekspos kode kesalahan terpisah untuk model yang tersembunyi, ditunda, atau non-publik. Perlakukan model publik yang tidak tersedia sama seperti kesalahan pencocokan: periksa did_you_mean, suggestions, dan hint, lalu coba ulang dengan model publik yang didukung.

insufficient_balance (402)

Saat saldo akun terlalu rendah untuk estimasi biaya:

{
  "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 berisi model yang lebih murah daripada estimasi biaya yang dapat dipilih oleh agen.

all_channels_failed (503)

Ketika semua saluran hulu untuk sebuah model tidak tersedia:

{
  "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 bernilai false ketika alasannya adalah no_channels (tidak ada saluran yang dikonfigurasi untuk model ini). Nilainya true hanya untuk kegagalan sementara seperti trip circuit breaker atau kehabisan kuota.

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."
  }
}

Nilai retry_after dihitung dari waktu reset jendela batas laju yang sebenarnya.

Endpoint yang kompatibel dengan OpenAI menggunakan tipe kesalahan publik stabil TokenLab seperti rate_limit_exceeded, upstream_error, dan all_channels_failed. Endpoint yang kompatibel dengan Anthropic dan Gemini menggunakan bentuk respons asli mereka sendiri.

context_length_exceeded (400)

Ketika input melebihi jendela konteks model (kesalahan hulu, diperkaya dengan petunjuk):

{
  "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."
  }
}

Penemuan Endpoint Native

Jangan simpulkan ketersediaan protokol native dari nama model atau provider, maupun dari header respons Chat. Sebelum memilih endpoint native, baca GET /v1/models/{model} dan gunakan hanya format permintaan yang diiklankan oleh detail model serta didukung route dengan protokol yang sama. Field yang dibaca adalah tokenlab.accepted_request_formats.

Format permintaan	Endpoint
Chat Completions	`/v1/chat/completions`
Responses	`/v1/responses`
Messages	`/v1/messages`
Gemini	`/v1beta/models/{model}:generateContent`

Format yang diiklankan menentukan ketersediaan endpoint; dukungan field dan tool tertentu tetap bergantung pada upstream.

Peningkatan /v1/models

/v1/models sekarang membawa metadata rekomendasi non-chat yang dapat digunakan agen sebelum mereka memanggil endpoint image, video, music, 3D, TTS, STT, embedding, rerank, atau translation.

{
  "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"
        }
      }
    }
  }
}

Bidang	Nilai	Deskripsi
`category`	`chat`, `image`, `video`, `audio`, `tts`, `stt`, `3d`, `embedding`, `rerank`	Jenis model
`pricing_unit`	`per_token`, `per_image`, `per_second`, `per_request`	Cara model ditagihkan
`cache_pricing`	object or `null`	Hanya dikembalikan saat model punya harga prompt cache upstream khusus model.
`agent_preferences.<scene>`	object	Snapshot rekomendasi non-chat yang hanya dikembalikan pada `GET /v1/models?recommended_for=<scene>`

Saat recommended_for ada, agent_preferences diturunkan dari snapshot tingkat keberhasilan 24 jam yang di-cache:

Jendela: 24 jam
Cache snapshot: stale-while-revalidate
status = "ready" berarti model memiliki sampel terbaru yang cukup untuk berpartisipasi dalam perankingan
status = "insufficient_samples" berarti model tetap terlihat tetapi tidak diperingkat di atas model yang memiliki skor

Penyaringan Kategori

GET https://api.tokenlab.sh/v1/models?category=chat          # Chat models only
GET https://api.tokenlab.sh/v1/models?category=image         # Image generation models
GET https://api.tokenlab.sh/v1/models?tag=coding&category=chat  # Coding-optimized chat models

Penemuan Rekomendasi

Untuk alur kerja non-chat, agen harus mengambil daftar singkat rekomendasi saat ini terlebih dahulu:

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

Nilai recommended_for yang valid adalah:

image
video
music
3d
tts
stt
embedding
rerank
translation

Jika category dan recommended_for keduanya ada, keduanya harus cocok secara tepat. Alur agen yang direkomendasikan:

GET /v1/models?recommended_for=<scene>
Pilih model pertama dengan agent_preferences.<scene>.status == "ready"
Panggil endpoint secara eksplisit dengan model=<selected>
Untuk kesalahan sementara saja, coba ulang dengan model ready berikutnya

llms.txt

Ringkasan API yang dapat dibaca mesin tersedia di:

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

Ini mencakup:

Template panggilan pertama dengan contoh yang bekerja
Nama model umum (dihasilkan secara dinamis dari data penggunaan)
Semua 12 endpoint API
Parameter filter untuk penemuan model
Panduan penanganan kesalahan

Agen AI yang membaca llms.txt sebelum panggilan API pertama mereka biasanya dapat berhasil pada percobaan pertama.

Penggunaan dalam Kode Agen

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;
  }
}

Prinsip Desain

Gagal cepat, berikan informasi

Kesalahan dikembalikan segera dengan semua data yang dibutuhkan agen untuk mengoreksi diri.

Tanpa pengalihan otomatis

API tidak pernah diam-diam menggantikan model dengan model lain. Agen yang memutuskan.

Saran berbasis data

Semua rekomendasi berasal dari data produksi, bukan daftar yang dikodekan statis.

Kompatibel ke belakang

Semua field petunjuk bersifat opsional. Klien yang ada tidak melihat perbedaan.

Memulai

Panduan inti

Panduan media

✨ Agent-First API

Ikhtisar

Bidang Petunjuk Kesalahan

Contoh Kode Kesalahan

model_not_found (400)

insufficient_balance (402)

all_channels_failed (503)

rate_limit_exceeded (429)

context_length_exceeded (400)

Penemuan Endpoint Native

Peningkatan /v1/models

Penyaringan Kategori

Penemuan Rekomendasi

llms.txt

Penggunaan dalam Kode Agen

Python (OpenAI SDK)

JavaScript (OpenAI SDK)

Prinsip Desain

Gagal cepat, berikan informasi

Tanpa pengalihan otomatis

Saran berbasis data

Kompatibel ke belakang

​Ikhtisar

​Bidang Petunjuk Kesalahan

​Contoh Kode Kesalahan

​model_not_found (400)

​insufficient_balance (402)

​all_channels_failed (503)

​rate_limit_exceeded (429)

​context_length_exceeded (400)

​Penemuan Endpoint Native

​Peningkatan /v1/models

​Penyaringan Kategori

​Penemuan Rekomendasi

​llms.txt

​Penggunaan dalam Kode Agen

​Python (OpenAI SDK)

​JavaScript (OpenAI SDK)

​Prinsip Desain

Gagal cepat, berikan informasi

Tanpa pengalihan otomatis

Saran berbasis data

Kompatibel ke belakang

Ikhtisar

Bidang Petunjuk Kesalahan

Contoh Kode Kesalahan

model_not_found (400)

insufficient_balance (402)

all_channels_failed (503)

rate_limit_exceeded (429)

context_length_exceeded (400)

Penemuan Endpoint Native

Peningkatan /v1/models

Penyaringan Kategori

Penemuan Rekomendasi

llms.txt

Penggunaan dalam Kode Agen

Python (OpenAI SDK)

JavaScript (OpenAI SDK)

Prinsip Desain