Quickstart

Kirim request pertama Anda dalam hitungan menit. Gateway menerima format request OpenAI apa adanya — cukup ganti base URL dan API key.

bash

curl https://ai.cutad.web.id/v1/chat/completions \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nama-model-anda",
    "messages": [{"role":"user","content":"Halo"}]
  }'

python

from openai import OpenAI
client = OpenAI(
    base_url="https://ai.cutad.web.id/v1",
    api_key="cag_xxxxx",
)
resp = client.chat.completions.create(
    model="nama-model-anda",
    messages=[{"role":"user","content":"Halo"}],
)
print(resp.choices[0].message.content)

Autentikasi

Semua request harus menyertakan header Authorization dengan API key Anda.

http

Authorization: Bearer ***

API key dibuat dari Dashboard → API Keys.
Format key: cag_ + 32 karakter base64url.
Key disimpan sebagai SHA-256 hash di database — kami tidak pernah menyimpan key dalam bentuk asli.

Streaming (SSE)

Gateway mendukung streaming response dengan Server-Sent Events. Tambahkan stream: true pada request body — gateway otomatis menyertakan token usage di akhir stream.

bash

curl https://ai.cutad.web.id/v1/chat/completions \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nama-model-anda",
    "messages": [{"role":"user","content":"Halo"}],
    "stream": true
  }' | head -20

Gateway otomatis menambahkan stream_options: { include_usage: true } untuk mengirimkan token usage di akhir stream.
Response berisi chunk data: {...} dan diakhiri dengan data: [DONE].
Error di tengah stream juga dikirim dalam format SSE yang sama.

Rate Limit & Quota

Gateway menerapkan dua lapisan proteksi agar penggunaan tetap adil dan terlindung dari penyalahgunaan.

Rate Limit per Menit (RPM) — berdasarkan plan, dihitung per-user dengan window 60 detik (in-memory).
Monthly Quota — total request per bulan. Jika terlewati, request ditolak hingga reset.
Credit System — jika plan mengaktifkan credit (token-based), setiap request memotong credit berdasarkan token usage (input + output).

Rate limit in-memory (bukan Redis) — akan reset saat proses restart. Untuk rate limit yang persisten, hubungi admin.

Response header yang dikembalikan:

Header	Deskripsi
`x-ratelimit-remaining`	Sisa request dalam window 60 detik ini
`x-ratelimit-reset`	Timestamp (ms) kapan window akan reset
`retry-after`	Detik sampai window reset (hanya saat 429)

Endpoint Reference

Daftar endpoint yang tersedia di gateway, dikelola langsung oleh admin dan selalu up-to-date.

Models

GEThttps://ai.cutad.web.id/v1/modelsAPI Key

List Models

Mengembalikan daftar semua model yang tersedia di gateway.

Sample Response

json

{
  "data": [
    {
      "id": "nama-model-anda",
      "object": "model",
      "owned_by": "cutad"
    }
  ],
  "object": "list"
}

Chat

POSThttps://ai.cutad.web.id/v1/chat/completionsAPI Key

Chat Completion

Membuat completion obrolan format OpenAI-compatible.

Request Body

json

{
  "model": "nama-model-anda",
  "messages": [
    {
      "role": "user",
      "content": "Halo"
    }
  ],
  "max_tokens": 100
}

Embeddings

POSThttps://ai.cutad.web.id/v1/embeddingsAPI Key

Embeddings

Menghasilkan embedding vektor untuk teks input.

Request Body

json

{
  "input": "teks contoh",
  "model": "nama-model-anda"
}

Credit System

Gateway mendukung sistem kredit berbasis token untuk kontrol biaya yang presisi.

Jika plan Anda mengaktifkan credit (creditAmount > 0), setiap request memotong credit berdasarkan jumlah token yang digunakan (input + output).

creditAmount — jumlah kredit yang diberikan per periode reset.
creditResetPeriod — DAILY, WEEKLY, atau MONTHLY. Kredit otomatis reset pada periode berikutnya.
creditBalance — sisa kredit yang tersedia.
Atomic deduction — potongan dilakukan secara atomik via SQL UPDATE ... WHERE creditBalance >= amount untuk mencegah race condition.
Overage — jika kredit tidak cukup, saldo diset ke 0 dan overage dicatat di log.

Saat kredit habis, gateway mengembalikan response 429:

json

{
  "error": {
    "message": "Credit exhausted. 100,000 tokens/MONTHLY. Resets 1 Agustus 2026, 00:00.",
    "type": "quota_exceeded",
    "code": "insufficient_quota",
    "param": null,
    "credits": {
      "remaining": 0,
      "limit": 100000,
      "resetPeriod": "MONTHLY"
    }
  }
}

Model Routing

Gateway melakukan transformasi model sebelum meneruskan request ke upstream provider — transparan bagi aplikasi Anda.

Model name rewrite — public name (misal: gpt-4o) diganti dengan upstream model name.
System prompt injection — systemPromptPrefix dan systemPromptSuffix ditambahkan ke system message.
Parameter override — bodyOverridesJson dan paramOverridesJson diterapkan ke request body.
Header override — headerOverridesJson diterapkan ke upstream request.
Response rewrite — nama model di response dikembalikan ke public name.

Webhooks

Terima event real-time setiap kali request API selesai, langsung ke endpoint Anda.

Konfigurasi

Tambahkan URL webhook di Dashboard → Webhooks. Setiap event dikirim dengan header x-webhook-event dan x-webhook-secret untuk verifikasi.

Event Types

Event	Deskripsi
`request.completed`	Request API selesai (sukses atau error)

Payload Format

Setiap webhook dikirim sebagai POST dengan body JSON:

json

{
  "event": "request.completed",
  "timestamp": "2026-07-22T10:30:00.000Z",
  "data": {
    "endpoint": "/v1/chat/completions",
    "method": "POST",
    "status": 200,
    "latencyMs": 150
  }
}

Headers: x-webhook-event (event type), x-webhook-secret (secret untuk verifikasi). Delivery dicatat di database dengan status SUCCESS/FAILED.

Signature Verification

Verifikasi webhook dengan membandingkan header x-webhook-secret dengan secret yang Anda konfigurasi:

python

import hmac, hashlib, json

def verify_webhook(request, expected_secret):
    received = request.headers.get("x-webhook-secret", "")
    return hmac.compare_digest(received, expected_secret)

# Usage
if verify_webhook(request, "your-webhook-secret"):
    payload = json.loads(request.body)
    print(f"Event: {payload['event']}")
    print(f"Data: {payload['data']}")

Integrasi dengan agent

Panduan pasang CutadAI di OpenClaw & Hermes.

Buka Panduan

Error Codes

Gateway mengembalikan error dalam format OpenAI standar dengan pesan yang jelas untuk setiap kasus.

Kode	Sub-case	Deskripsi
401	Missing Authorization	Header Authorization tidak ada
401	Invalid API key	Key tidak ditemukan, tidak aktif, atau sudah direvok
403	Account suspended	Akun pengguna tidak aktif
403	No active subscription	Tidak ada langganan yang aktif
429	Rate limit exceeded	RPM limit terlewati (dengan retry-after header)
429	Monthly quota exceeded	Total request bulanan terlewati
429	Credit exhausted	Credit token habis (dengan credits object di response)
404	Model not found	Model tidak tersedia di gateway
502	No active provider	Admin belum mengkonfigurasi provider
502	Upstream error	Error dari upstream (disanitasi, tidak bocorkan konten)

Error Sanitization

Gateway menyanitasi error dari upstream untuk mencegah kebocoran konten chat Anda.

Error message dari upstream diganti dengan pesan generik yang aman:

json

{
  "error": {
    "message": "Upstream error. Contact support if this persists.",
    "type": "upstream_error"
  }
}

Error sanitization juga berlaku untuk SSE streaming chunks. Stack trace dan request_id dari upstream dihapus.

Retry & Timeout

Gateway mencoba kirim ulang request ke upstream jika terjadi network error.

Max retries — dikonfigurasi per provider (default: 2).
Backoff — 500ms × (attempt + 1), linear backoff.
Timeout — dikonfigurasi per provider (default: 300 detik).
Retry condition — hanya network error, bukan HTTP error response.

Butuh bantuan? Tim kami siap membantu integrasi Anda.

Hubungi kami

Bangun dengan CutadAI Gateway.

Quickstart

Autentikasi

Streaming (SSE)

Rate Limit & Quota

Endpoint Reference

Models

List Models

Chat

Chat Completion

Embeddings

Embeddings

Credit System

Model Routing

Webhooks

Error Codes

Error Sanitization

Retry & Timeout