Reference

Panduan Integrasi

Detail teknis buat integrasi Lumina API ke aplikasi kamu — format request/response, error handling, rate limit, dan session memory.

1. Format Request

Semua endpoint dipanggil lewat HTTP GET dengan parameter di query string, ke base URL:

Base URL

https://api.luminaa.web.id

API key dikirim lewat header x-api-key, bukan query param (lebih aman, gak ke-log di URL/history):

cURL

curl "https://api.luminaa.web.id/api/ai-chat/lumina?query=halo" \
  -H "x-api-key: lumina-xxxxxxxxxxxx"

2. Format Response

Setiap response selalu JSON dengan field status sebagai indikator sukses/gagal.

Sukses:

200 OK

{
  "status": true,
  "statusCode": 200,
  "creator": "Xena",
  "result": {
    "reply": "Halo! Ada yang bisa dibantu?",
    "model": "lumina-1",
    "session": "abc123"
  }
}

Gagal: field result diganti error (string).

4xx / 5xx

{
  "status": false,
  "statusCode": 401,
  "creator": "Xena",
  "error": "API key diperlukan."
}

Selalu cek data.status dulu sebelum baca result:

JavaScript

const data = await res.json()
if (!data.status) {
  console.error(data.error)
} else {
  console.log(data.result.reply)
}

3. Error Handling

Status code yang mungkin dibalikin:

200	OK	Request sukses, cek result
400	Bad Request	Parameter wajib gak diisi / format salah
401	Unauthorized	API key gak ada / gak valid / dicabut
404	Not Found	Endpoint atau resource gak ketemu
429	Too Many Requests	Limit per menit tercapai, lihat header rate limit
500	Internal Server Error	Error di provider AI / server, coba lagi

Untuk 429, sebaiknya tunggu sesuai field retryAfter di body response sebelum retry, jangan langsung spam ulang.

4. Rate Limit Headers

Tiap response (sukses atau gagal) selalu bawa 2 header ini:

X-RateLimit-Limit	Batas request per menit buat key/IP kamu (20 tanpa key, 100 dengan key)
X-RateLimit-Remaining	Sisa kuota di window 1 menit saat ini

Body response pas kena limit juga ngasih estimasi waktu tunggu:

429 Too Many Requests

{
  "status": false,
  "statusCode": 429,
  "error": "Limit API key tercapai (100 req/menit). Coba lagi nanti.",
  "retryAfter": "37s"
}

5. Session / Memory Percakapan

Sebagian endpoint AI Chat (cek param session di halaman endpoint) bisa nyimpen riwayat percakapan kalau kamu kirim ID session yang konsisten:

cURL

# Pesan pertama
curl "https://api.luminaa.web.id/api/ai-chat/lumina?query=nama%20gw%20budi&session=chat-001" \
  -H "x-api-key: lumina-xxxxxxxxxxxx"

# Pesan kedua, session sama → AI masih ingat
curl "https://api.luminaa.web.id/api/ai-chat/lumina?query=siapa%20nama%20gw&session=chat-001" \
  -H "x-api-key: lumina-xxxxxxxxxxxx"

ID session bebas string apa aja (UUID, user ID, dst) — asal konsisten per percakapan.

6. Best Practices

Jangan hardcode API key di kode client-side publik (frontend yang ke-deploy) — taruh di environment variable server-side.
Tangani status 429 dengan exponential backoff, jangan retry langsung berkali-kali.
Cek data.status sebelum proses result, jangan asumsi selalu sukses.
Pakai 1 API key per aplikasi/proyek — gampang dicabut individual kalau bocor, gak ganggu aplikasi lain.
Manfaatin session buat chatbot biar konteks percakapan gak hilang tiap request.

Buat API Key Lihat Semua Endpoint Coba di Playground