I. Gambaran Umum
Jizhi API menyediakan akses relay yang kompatibel dengan Anthropic Messages API (/v1/messages) bagi pengembang. Anda hanya perlu mengirimkan permintaan ke gateway situs kami dan mengganti Key autentikasi dengan kunci sk- yang dibuat di "Pusat Pengguna - Kunci API", maka Anda dapat langsung menggunakan model seri Claude tanpa perlu mengubah kode yang sudah ada.
Model yang tersedia saat ini mengacu pada Model Plaza (seperti claude-sonnet-5, claude-opus-5, claude-sonnet-4-6, claude-opus-4-8, dll.). Daftar lengkap dan harga satuan dapat diperiksa kapan saja melalui GET /v1/models.
II. Alamat Antarmuka
| Metode | Path | Keterangan |
|---|---|---|
| POST | /v1/messages | Gerbang relay, body permintaan adalah payload Anthropic /v1/messages |
| GET | /v1/models | Daftar model dan harga satuan (tidak perlu autentikasi) |
Alamat Gateway: https://www.relay-api.com. Isi path permintaan sesuai dengan tabel di atas.
III. Metode Autentikasi
Buat kunci di "Pusat Pengguna → Kunci API" dengan format sk-xxxxxxxx. Sertakan kunci saat melakukan panggilan menggunakan salah satu cara berikut:
- Header Authorization:
Authorization: Bearer sk-kunci-anda(Direkomendasikan, kompatibel dengan sebagian besar SDK) - Header x-api-key:
x-api-key: sk-kunci-anda
Jika kunci tidak valid, dinonaktifkan, atau saldo tidak mencukupi, sistem akan mengembalikan status 401/403. Silakan periksa status kunci dan saldo akun Anda terlebih dahulu.
IV. Memulai Cepat (curl)
4.1 Percakapan Non-streaming
curl -X POST https://www.relay-api.com/v1/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-kunci-anda" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Perkenalkan dirimu dalam satu kalimat"}
]
}'4.2 Menggunakan system prompt dan percakapan multi-putaran
curl -X POST https://www.relay-api.com/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: sk-kunci-anda" \
-d '{
"model": "claude-opus-5",
"max_tokens": 2048,
"system": "Anda adalah insinyur dokumentasi teknis yang teliti.",
"messages": [
{"role": "user", "content": "Apa header autentikasi untuk Claude Messages API?"},
{"role": "assistant", "content": "Gunakan x-api-key atau Authorization: Bearer untuk menyertakan kunci."},
{"role": "user", "content": "Berikan contoh lain untuk permintaan streaming."}
],
"metadata": {"request_id": "demo-001"}
}'metadata.request_id akan dicatat dalam log penggunaan untuk memudahkan rekonsiliasi di "Pusat Pengguna → Detail Penggunaan".
V. Parameter Permintaan
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
| model | string | Ya | Slug model, misal claude-sonnet-5 |
| max_tokens | int | Ya | Jumlah token output maksimum, disarankan 1~64000 |
| messages | array | Ya | Pesan percakapan, elemen berupa {role, content}, role: user / assistant |
| system | string | Tidak | System prompt |
| temperature | number | Tidak | Temperatur sampling, default 1.0, rentang 0~1 |
| top_p | number | Tidak | Core sampling, default 0.999 |
| stream | bool | Tidak | Apakah menggunakan streaming, default false |
| stop_sequences | array | Tidak | Urutan berhenti (stop sequences) |
| metadata.request_id | string | Tidak | ID permintaan kustom untuk rekonsiliasi |
VI. Struktur Respons
Permintaan non-streaming mengembalikan struktur Anthropic Messages standar:
{
"id": "msg_01ABCDEFG",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-5",
"content": [
{"type": "text", "text": "Halo! Saya Claude."}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 12,
"output_tokens": 18,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0
}
}| Field | Keterangan |
|---|---|
| id | ID unik pesan |
| content[].type | Tipe blok konten, text / thinking dll. |
| content[].text | Isi teks |
| stop_reason | Alasan berhenti: end_turn / max_tokens / stop_sequence |
| usage.input_tokens | Jumlah token input (dasar penagihan) |
| usage.output_tokens | Jumlah token output (dasar penagihan) |
| usage.cache_read_input_tokens | Jumlah token input yang hit cache (ditagih sesuai harga baca cache) |
| usage.cache_creation_input_tokens | Jumlah token yang ditulis ke cache (ditagih sesuai harga tulis cache) |
VII. Output Streaming
Jika body permintaan menambahkan "stream": true, server akan mengembalikan data per blok melalui SSE (Server-Sent Events). Tipe event sama dengan Anthropic:
event: message_start
data: {"type": "message_start", "message": {"id": "msg_...", "model": "claude-sonnet-5"}}
event: content_block_delta
data: {"type": "content_block_delta", "delta": {"type": "text_delta", "text": "Halo"}}
event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn"}, "usage": {"output_tokens": 18}}
event: message_stop
data: {"type": "message_stop"}Klien perlu mengurai JSON berdasarkan baris data:, mengabaikan baris event: dan baris kosong; menerima message_stop berarti aliran berakhir. Penagihan dilakukan di sisi server berdasarkan penggunaan total permintaan, terlepas dari streaming atau tidak.
VIII. Kode Kesalahan Umum
| Kode Status HTTP | Makna | Saran Penanganan |
|---|---|---|
| 400 | Parameter permintaan tidak valid (kurang model/max_tokens, model tidak aktif, dll.) | Koreksi body permintaan sesuai pesan respons |
| 401 | Tidak membawa atau membawa kunci API yang tidak valid | Periksa header Authorization / x-api-key |
| 403 | Kunci dinonaktifkan, saldo habis, atau kunci tidak diizinkan untuk model/rute ini | Isi ulang, periksa status kunci atau sesuaikan otorisasi kunci |
| 404 | Model yang diminta tidak ada | Periksa model yang tersedia melalui GET /v1/models |
| 429 | Permintaan terlalu sering atau terpicu pembatasan rate limit | Lakukan retry (dengan exponential backoff) |
| 500 | Kesalahan internal server | Coba lagi nanti; jika terus gagal, hubungi layanan pelanggan |
Body respons kesalahan distandarisasi sebagai {"code": kode_status, "message": "deskripsi_kesalahan", "data": null}.
IX. Penggunaan dan Saldo
- Setiap panggilan akan dipotong biayanya secara real-time berdasarkan penggunaan token × harga satuan model × multiplier rute. Harga dan rute dapat dilihat di
GET /v1/models. - Setelah login, Anda dapat melihat catatan panggilan (model, token, biaya, status) di "Pusat Pengguna → Penggunaan API".
- Jika saldo tidak mencukupi, panggilan akan mengembalikan status 403, dan akan pulih segera setelah pengisian ulang.
Penjelasan Base URL: Situs ini menerima /v1beta/models/... dan /v1beta/v1beta/models/... (serta /v1/... dan /v1/v1/...), sehingga apakah klien menambahkan /v1 atau /v1beta sendiri tidak mempengaruhi panggilan: Base URL dapat diisi dengan root domain atau alamat dengan /v1beta. ID Model silakan disalin dari "ID Model" di sudut kanan atas halaman "Token" di konsol.