Developer Docs

API Reference

ZaganRouter adalah gateway AI yang 100% OpenAI-compatible. Ganti base_url, pakai API key Anda, dan semua kode OpenAI SDK Anda berjalan tanpa perubahan lain — chat completions, streaming SSE, dan catalog model.

OpenAI-compatibleStreaming SSEBearer AuthMulti-provider
Base URL

Semua request API ditujukan ke satu endpoint ini. Tidak ada subdomain per region — gateway merutekan otomatis ke provider tercepat yang sehat.

Base URL
https://zaganrouter.cloud/v1

Quickstart

Kirim request pertama Anda dalam 30 detik. Ganti $ZG_API_KEY dengan key dari dashboard Anda.

curl
curl https://zaganrouter.cloud/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZG_API_KEY" \
  -d '{
    "model": "ZAI/GLM-4.6",
    "messages": [{"role": "user", "content": "Halo, kenalan dong!"}]
  }'

Authentication

ZaganRouter memakai Bearer token pada header Authorization. API key berformat sk-zg-... dan dibuat per-project di dashboard.

Jangan commit API key. Key disimpan satu kali sebagai hash + prefix; raw value hanya tampil sekali saat dibuat. Simpan di environment variable.
Header Authorization
Authorization: Bearer $ZG_API_KEY
Content-Type: application/json

Tanpa key valid, Anda akan dapat:

json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key."
  }
}

Chat Completions POST

Buat percakapan dengan model. Endpoint ini kompatibel 100% dengan /v1/chat/completions OpenAI — semua field standar didukung.

Endpoint
POST https://zaganrouter.cloud/v1/chat/completions

Request Body

ParameterTypeRequiredDeskripsi
modelstring✓ID model dari /v1/models (mis. ZAI/GLM-4.6)
messagesarray✓Daftar pesan {role, content}. role: system/user/assistant
temperaturenumber—0–2. Default 1. Kreativitas sampling.
max_tokensinteger—Batas token output. Affects credit cost.
streamboolean—true → SSE stream. Lihat Streaming.
top_pnumber—0–1. Nucleus sampling.
stopstring/array—Hingga 4 sequence stop.

Contoh Response

json
{
  "id": "chatcmpl-zg-9f3a...",
  "object": "chat.completion",
  "created": 1783267780,
  "model": "ZAI/GLM-4.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Halo! Saya ZaganRouter AI. Salam kenal!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 14,
    "total_tokens": 26
  }
}

Streaming (SSE) STREAM

Set "stream": true untuk menerima token secara incremental via Server-Sent Events. Format identik dengan OpenAI — tiap chunk dipisah data: dan stream diakhiri data: [DONE].

curl
curl https://zaganrouter.cloud/v1/chat/completions \
  -H "Authorization: Bearer $ZG_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "ZAI/GLM-4.6",
    "stream": true,
    "messages": [{"role": "user", "content": "Ceritakan tentang dirimu"}]
  }'

Format SSE chunk

text
data: {"id":"chatcmpl-zg-9f3a","object":"chat.completion.chunk","choices":[{"delta":{"content":"Halo"},"index":0}]}

data: {"id":"chatcmpl-zg-9f3a","object":"chat.completion.chunk","choices":[{"delta":{"content":"!"},"index":0}]}

data: [DONE]

List Models GET

Ambil semua model yang tersedia untuk API key Anda. Berguna untuk membangun UI pemilih model dinamis.

bash
curl https://zaganrouter.cloud/v1/models \
  -H "Authorization: Bearer $ZG_API_KEY"

Response

json
{
  "object": "list",
  "data": [
    {
      "id": "ZAI/GLM-4.6",
      "object": "model",
      "created": 1783267780,
      "owned_by": "ZAI"
    },
    {
      "id": "MINIMAX/MiniMax-M2",
      "object": "model",
      "created": 1783267780,
      "owned_by": "MINIMAX"
    }
  ]
}

Errors

Semua error mengikuti format OpenAI agar SDK menanganinya otomatis. Struktur: { error: { type, code, message } }.

StatustypecodePenyebab
400invalid_request_errorinvalid_bodyBody JSON tidak valid / field salah.
401authentication_errorinvalid_api_keyKey tidak ada / salah format / disabled.
402billing_errorsubscription_inactiveLangganan habis — perpanjang plan.
403permission_errormodel_not_allowedModel tidak tersedia di plan Anda.
404invalid_request_errormodel_not_foundID model tidak terdaftar.
429rate_limit_errorrate_limit_exceededTerlalu cepat. Lihat header retry_after.
429quota_exceededfive_hour_quota_exceededQuota 5-jam habis. Tunggu sliding window reset.
429quota_exceededweekly_quota_exceededQuota mingguan habis. Reset di reset_at.
502provider_errorprovider_unavailableSemua provider gagal. Auto-fallback ke upstream gagal total.
503service_errorquota_backend_unavailableQuota service (Redis) tidak terjangkau — fail-closed.

Rate Limits & Quota

ZaganRouter menerapkan quota fail-closed: jika quota backend (Redis) tidak terjangkau, request ditolak (503) — tidak pernah lolos tanpa cek.

Rate limit per-minute

Mencegah burst abuse. Header retry_after pada error 429 memberitahu kapan coba lagi.

Quota 5-jam (sliding)

Token usage dihitung dalam window 5 jam bergulir. Quota baru tersedia bertahap saat usage lama keluar dari window.

Quota mingguan

Total credit per plan. Saat habis, hard stop. Reset otomatis tiap minggu pada reset_at.

Reservasi atomic

Reserve → commit → refund dalam satu Redis Lua call. Tidak ada race condition: request paralel tidak bisa melebihi limit.

SDKs & Libraries

Karena 100% OpenAI-compatible, SDK resmi OpenAI langsung jalan. Cukup ganti base_url:

Python
openai
pip install openai
Node.js
openai
npm install openai
Go
go-openai
go get github.com/sashabaranov/go-openai
.NET
OpenAI
dotnet add package OpenAI

Siap mulai?

Buat project, dapatkan API key, kirim request pertama dalam < 1 menit.

Daftar GratisLihat Pricing