Clouvia RouterRouter ClouviaID
REFERENSI PROTOKOL

Endpoint Gateway

Spesifikasi teknis seluruh endpoint resmi Clouvia Router. Gateway kami beroperasi di atas base URL https://router.clouvia.id/v1 dengan enkripsi TLS 1.3 dan kepatuhan penuh terhadap kontrak OpenAI API.

BASE URL:https://router.clouvia.id/v1
RESPONSE FORMAT:application/json / text/event-stream
AUTH TYPE:Authorization: Bearer <API_KEY>

Ringkasan Seluruh Endpoint

API REFERENCE
MethodEndpoint PathDeskripsi UtamaHeader Wajib
POST/v1/chat/completionsInferensi LLM cerdas, multi-turn chat, dan streaming SSE.Authorization: Bearer <API_KEY>
GET/v1/modelsDaftar katalog model AI aktif beserta status upstream.Authorization: Bearer <API_KEY>
GET/v1/balanceSaldo akun: token berbayar, token gratis, dan total.Authorization: Bearer <API_KEY>
POST/v1/responsesOpenAI Responses API untuk Codex CLI dan ChatGPT Desktop.Authorization: Bearer <API_KEY>
POST/v1/messagesAnthropic Messages API untuk Claude Code CLI dan SDK Anthropic.x-api-key / Authorization: Bearer
GET/v1/key/introspectCek validitas key, hak akses scope, dan sisa saldo token.Authorization: Bearer <API_KEY>

1. POST /v1/chat/completions

Endpoint utama untuk eksekusi dialog dan penalaran kognitif. Mendukung parameter standar OpenAI seperti model, messages, temperature, max_tokens, serta stream: true untuk streaming token waktu nyata.

Parameter Request Body (JSON)

SCHEMA
FieldTipe DataWajib / OpsionalKeterangan
modelstringWajibSlug model target (contoh: coding-high, claude-opus-4.6).
messagesarray<object>WajibArray percakapan dengan format { role: string, content: string }.
streambooleanOpsionalJika true, mengembalikan response stream SSE (text/event-stream).
temperaturenumberOpsionalKreativitas sampling antara 0.0 s/d 2.0 (default 0.7; coding disarankan 0.2).
max_tokensintegerOpsionalBatas maksimal token jawaban yang digenerate (disarankan 8192 s/d 32768).
cURL Request (Standard)bash
1curl https://router.clouvia.id/v1/chat/completions \
2  -H "Authorization: Bearer $CLOUVIA_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "coding-high",
6    "messages": [
7      {"role": "system", "content": "Kamu asisten arsitektur teknis."},
8      {"role": "user", "content": "Jelaskan perbedaan TCP dan UDP secara singkat."}
9    ],
10    "temperature": 0.3,
11    "max_tokens": 1024
12  }'
JSON Response (HTTP 200 OK)json
1{
2  "id": "chatcmpl-01M2K5X1XN6R84VPVADSG0THDM",
3  "object": "chat.completion",
4  "created": 1726462800,
5  "model": "coding-high",
6  "choices": [
7    {
8      "index": 0,
9      "message": {
10        "role": "assistant",
11        "content": "TCP adalah protokol connection-oriented yang menjamin urutan dan keutuhan paket data (reliable). UDP adalah protokol connectionless yang memprioritaskan kecepatan tanpa mekanisme handshake atau retransmisi (unreliable)."
12      },
13      "finish_reason": "stop"
14    }
15  ],
16  "usage": {
17    "prompt_tokens": 28,
18    "completion_tokens": 46,
19    "total_tokens": 74
20  }
21}

2. GET /v1/models

Mengambil daftar seluruh model kecerdasan buatan aktif yang dapat dipanggil oleh API key Anda. Kompatibel penuh dengan pemanggilan method client.models.list() di SDK resmi OpenAI.

cURL List Modelsbash
1curl https://router.clouvia.id/v1/models \
2  -H "Authorization: Bearer $CLOUVIA_API_KEY"
JSON Output Katalog Modeljson
1{
2  "object": "list",
3  "data": [
4    {
5      "id": "coding-high",
6      "object": "model",
7      "created": 1726462800,
8      "owned_by": "clouvia",
9      "permission": [],
10      "root": "coding-high",
11      "parent": null
12    },
13    {
14      "id": "claude-opus-4.6",
15      "object": "model",
16      "created": 1726462800,
17      "owned_by": "anthropic",
18      "permission": [],
19      "root": "claude-opus-4.6",
20      "parent": null
21    },
22    {
23      "id": "gpt-5.6-luna",
24      "object": "model",
25      "created": 1726462800,
26      "owned_by": "openai",
27      "permission": [],
28      "root": "gpt-5.6-luna",
29      "parent": null
30    }
31  ]
32}

Cek saldo token via API key

Gunakan GET /v1/balance dengan API key milik akun. Isi environment variable CLOUVIA_API_KEY pada server Anda. Tidak perlu login browser, cookie, CSRF, atau scope baru. Jangan kirim secret lewat URL atau query parameter.

GET /v1/balancebash
1curl https://router.clouvia.id/v1/balance \
2  -H "Authorization: Bearer $CLOUVIA_API_KEY"
Contoh respons ilustratif, bukan saldo riiljson
1{
2  "key_prefix": "clv_live_example",
3  "last4": "demo",
4  "name": "Example key",
5  "scopes": ["chat.completions", "models.read"],
6  "status": "active",
7  "balance": "1000000.000000",
8  "free_balance": "5000000.000000",
9  "total_balance": "6000000.000000",
10  "unit": "token",
11  "rate_limits": { "rpm": 100, "daily_limit": null },
12  "expires_at": null
13}
Saldo milik akun, bukan per key

Semua API key pada akun yang sama membaca saldo yang sama langsung dari database. Endpoint ini hanya membaca: tidak memanggil model AI dan tidak mendebit token. Respons memakai Cache-Control: private, no-store.

Nilai saldo berupa string desimal dengan 6 angka di belakang titik agar presisi tetap terjaga. Saldo negatif tetap ditampilkan jika akun memiliki defisit. Saldo gratis tidak menggantikan saldo berbayar.

Field respons

FieldTipeKeterangan
balancestringSaldo token berbayar akun.
free_balancestringSaldo gratis, hanya untuk model yang memenuhi aturan token gratis.
total_balancestringJumlah balance + free_balance. Bukan saldo yang seluruhnya bisa dipakai pada model berbayar.
unitstringtoken
key_prefix, last4, namestringIdentitas key tanpa secret atau hash.
scopes, statusarray, stringScope dan status key yang digunakan.
rate_limitsobjectrpm dan daily_limit key; null berarti tidak dikonfigurasi.
expires_atstring | nullWaktu kedaluwarsa ISO 8601, atau null.

Alias /api/v1/balance dan endpoint lama /v1/key/introspect atau /api/v1/key/introspect mengembalikan struktur yang sama. Field balance lama tetap berupa string.

GET /api/v1/balancebash
1curl https://router.clouvia.id/api/v1/balance \
2  -H "Authorization: Bearer $CLOUVIA_API_KEY"
GET /v1/key/introspectbash
1curl https://router.clouvia.id/v1/key/introspect \
2  -H "Authorization: Bearer $CLOUVIA_API_KEY"
Jika akses ditolak

HTTP 401: header tidak ada, key invalid, KEY_REVOKED, KEY_EXPIRED, atau KEY_DISABLED. HTTP 403: ACCOUNT_SUSPENDED atau IP_NOT_ALLOWED. Respons error menggunakan object error dengan code dan message. Tidak ada saldo yang ditampilkan jika autentikasi gagal.

Response Header Khusus Telemetri

AUDIT HUD
Header NameContoh NilaiPenjelasan
X-Request-Id01M2K5X1XN6R...ID unik transmisi untuk audit dan pelacakan error log di konsol telemetri.
X-Coding-High-Passes2Jumlah pass penalaran kognitif yang dieksekusi (khusus model coding-high).
X-Tokens-Billed74Total debit token yang dipotong secara atomik dari saldo dompet Anda.