✨ Agent-First API

Ikhtisar

Agent-First API LemonData memperkaya respons kesalahan dengan petunjuk terstruktur yang dapat diurai dan ditindaklanjuti langsung oleh agen AI — tanpa pencarian web, tanpa mencari dokumentasi, tanpa tebak-tebakan. Setiap respons kesalahan menyertakan field opsional seperti did_you_mean, suggestions, hint, retryable, dan retry_after di dalam objek error standar. Field-field ini kompatibel ke belakang — klien yang tidak menggunakannya tidak akan melihat perbedaan.

Bidang Petunjuk Kesalahan

Semua field petunjuk adalah ekstensi opsional di dalam objek error:

Field	Type	Description
`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.lemondata.cc/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://lemondata.cc/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: 60 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 60/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 LemonData 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."
  }
}

Header Endpoint Native

Saat Anda memanggil /v1/chat/completions dengan model yang memiliki endpoint native (Anthropic atau Gemini), respons sukses menyertakan header optimisasi:

X-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance (no format conversion).
X-LemonData-Native-Endpoint: /v1/messages

Penyedia Model	Endpoint yang Disarankan	Manfaat
Anthropic (Claude)	`/v1/messages`	Tanpa konversi format, pemikiran diperpanjang, caching prompt
Google (Gemini)	`/v1beta/gemini`	Tanpa konversi format, grounding, pengaturan keamanan
OpenAI	—	Chat completions sudah merupakan format native

Header ini muncul pada respons streaming maupun non-streaming.

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",
  "lemondata": {
    "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": {
          "score_source": "clickhouse_24h",
          "channel_id": null,
          "physical_model": null
        }
      }
    }
  }
}

Field	Values	Description
`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. Diskon semantic cache platform saja tidak lagi muncul sendiri di list.
`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
Snapshot cache: 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.lemondata.cc/v1/models?category=chat          # Chat models only
GET https://api.lemondata.cc/v1/models?category=image         # Image generation models
GET https://api.lemondata.cc/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.lemondata.cc/v1/models?recommended_for=image
GET https://api.lemondata.cc/v1/models?recommended_for=translation
GET https://api.lemondata.cc/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.lemondata.cc/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.lemondata.cc/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.lemondata.cc/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

Coding Agents

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

Header 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

Memulai

Panduan inti

Coding Agents

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

​Header 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)

Header Endpoint Native

Peningkatan /v1/models

Penyaringan Kategori

Penemuan Rekomendasi

llms.txt

Penggunaan dalam Kode Agen

Python (OpenAI SDK)

JavaScript (OpenAI SDK)

Prinsip Desain