v1 — OpenAI Compatible

Dokumentasi

Pengenalan

JapskuAI adalah gateway API yang kompatibel penuh dengan OpenAI. Semua request diarahkan ke base URL berikut, dengan format request/response persis seperti API OpenAI:

http://localhost:8080/v1

Artinya SDK OpenAI (Python, Node.js, LangChain, dsb.) langsung bisa dipakai — cukup ganti base_url dan api_key.

Autentikasi

Setiap request gateway membutuhkan API key yang diawali sk_, dikirim via header Authorization dengan skema Bearer:

header

Authorization: Bearer sk_xxxxxxxxxxxxxxxx

API key dibuat di dashboard. Key lengkap hanya ditampilkan sekali saat pembuatan — simpan baik-baik.

Chat Completions

POST /v1/chat/completions — endpoint utama untuk semua model chat.

request.sh

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "system", "content": "Kamu asisten yang membantu."},
      {"role": "user", "content": "Halo!"}
    ]
  }'

response.json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1756656000,
  "model": "kimi-k3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Halo! Ada yang bisa saya bantu?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 9,
    "total_tokens": 33
  }
}

Streaming (SSE)

Tambahkan "stream": true untuk menerima respons bertahap via Server-Sent Events. Gateway meneruskan chunk upstream apa adanya (passthrough) dengan keepalive, diakhiri data: [DONE].

stream.sh

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-plus",
    "stream": true,
    "messages": [{"role": "user", "content": "Tulis haiku tentang kopi"}]
  }'

stream-response.txt

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"}}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Kopi"}}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":" pagi"}}]}

data: [DONE]

Embeddings

POST /v1/embeddings — untuk model embedding seperti text-embedding-v3.

embed.sh

curl http://localhost:8080/v1/embeddings \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-v3",
    "input": "JapskuAI itu cepat"
  }'

response.json

{
  "object": "list",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.012, -0.034, "..."]}
  ],
  "model": "text-embedding-v3",
  "usage": {"prompt_tokens": 4, "total_tokens": 4}
}

Anthropic Messages

POST /v1/messages — kompatibel dengan Anthropic Messages API. Cocok untuk Claude Code atau tool apa pun yang memakai ANTHROPIC_BASE_URL. Auth via header x-api-key atau Authorization: Bearer. Mendukung streaming dengan format event Anthropic.

claude-code.sh

export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_AUTH_TOKEN=sk_xxx
# lalu jalankan Claude Code seperti biasa

messages.sh

curl http://localhost:8080/v1/messages \
  -H "x-api-key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "max_tokens": 1024,
    "system": "Kamu asisten yang membantu.",
    "messages": [{"role": "user", "content": "Halo!"}]
  }'

response.json

{
  "id": "msg_1788241330",
  "type": "message",
  "role": "assistant",
  "model": "kimi-k3",
  "content": [{"type": "text", "text": "Halo! Ada yang bisa saya bantu?"}],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {"input_tokens": 12, "output_tokens": 8}
}

Images

POST /v1/images/generations — generate gambar. Biaya flat 100.000 token per gambar (n maksimal 6).

image.sh

curl http://localhost:8080/v1/images/generations \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen-image", "prompt": "kucing astronot", "n": 1}'

response.json

{
  "created": 1788241358,
  "data": [{"url": "https://...", "revised_prompt": "kucing astronot"}]
}

Daftar Model

GET /v1/models mengembalikan katalog model dalam format OpenAI ({"object":"list","data":[...]}). Lihat halaman Model untuk katalog lengkap.

models.sh

curl http://localhost:8080/v1/models \
  -H "Authorization: Bearer sk_xxx"

Error Code

Error gateway selalu berbentuk {"error":{"message","type","code"}}:

Code	HTTP	Arti & Solusi
invalid_api_key	401	API key tidak valid, sudah dicabut (revoke), atau header Authorization tidak disertakan.
plan_expired	403	Masa aktif plan telah berakhir. Perpanjang atau beli plan baru di dashboard.
insufficient_quota	403	Kuota token habis — termasuk kuota sprint atau cap mingguan pada plan dual-layer.
rate_limit_exceeded	429	Melampaui batas request-per-menit (RPM) plan. Kurangi frekuensi request.
model_access_denied	403	Model yang diminta melebihi bobot maksimum (maxModelWeight) plan Anda.
upstream_timeout	504	Server upstream tidak merespons tepat waktu. Aman untuk dicoba ulang.

Rate-Limit Headers

Setiap respons gateway menyertakan header informatif berikut:

Header	Deskripsi
X-RateLimit-Remaining-Requests	Sisa request pada window RPM saat ini.
X-Sprint-Remaining-Tokens	Sisa token sprint (hanya plan dual-layer).
X-Weekly-Remaining-Tokens	Sisa token mingguan (hanya plan dual-layer).
X-Plan-Expires-At	Waktu kedaluwarsa plan dalam format RFC3339.

Tips: cek sisa kuota kapan saja tanpa mengurangi kuota lewat halaman Cek Usage atau GET /v1/usage.