Panduan Integrasi Claude API: Antarmuka Native Anthropic dan Konfigurasi Kunci

I. Gambaran Umum

AzzTimes menyediakan integrasi perantara yang kompatibel dengan Anthropic Messages API (/v1/messages) untuk para pengembang. Anda hanya perlu mengirimkan permintaan ke gateway kami dan mengganti kunci otentikasi dengan kunci sk- yang dibuat di "Pusat Pengguna - API Keys", sehingga Anda dapat langsung menggunakan seri model Claude tanpa perlu mengubah kode yang sudah ada.

Model yang tersedia saat ini mengacu pada daftar model di platform (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 API

Metode	Path	Keterangan
POST	/v1/messages	Gerbang penerusan perantara, body permintaan menggunakan payload Anthropic /v1/messages
GET	/v1/models	Daftar model dan harga satuan (tanpa otentikasi)

Alamat gateway: https://www.relay-api.com. Isi path permintaan sesuai dengan tabel di atas.

III. Metode Otentikasi

Buat kunci di "Pusat Pengguna → API Keys" dengan format sk-xxxxxxxx. Saat melakukan pemanggilan, sertakan kunci melalui 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.

IV. Memulai dengan 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-turn

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 seorang insinyur dokumentasi teknis yang teliti.",
    "messages": [
      {"role": "user", "content": "Apa header otentikasi untuk Claude Messages API?"},
      {"role": "assistant", "content": "Gunakan x-api-key atau Authorization: Bearer untuk menyertakan kunci."},
      {"role": "user", "content": "Berikan contoh permintaan streaming."}
    ],
    "metadata": {"request_id": "demo-001"}
  }'

metadata.request_id akan dicatat ke dalam log penggunaan, memudahkan rekonsiliasi di "Pusat Pengguna → Riwayat 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	Suhu sampling, default 1.0, rentang 0~1
top_p	number	Tidak	Nucleus sampling, default 0.999
stream	bool	Tidak	Apakah streaming diaktifkan, default false
stop_sequences	array	Tidak	Urutan berhenti
metadata.request_id	string	Tidak	ID permintaan kustom untuk rekonsiliasi

VI. Struktur Respon

Permintaan non-streaming mengembalikan struktur standar Anthropic Messages:

{
  "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	Konten 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	Token input yang berhasil di-cache (dikenakan biaya harga cache read)
usage.cache_creation_input_tokens	Token yang ditulis ke cache (dikenakan biaya harga cache write)

VII. Output Streaming

Setelah body permintaan menambahkan "stream": true, server akan mengembalikan data secara bertahap 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 harus mengurai JSON berdasarkan baris data: dan mengabaikan baris event: serta baris kosong. Penerimaan message_stop menandakan aliran selesai. Penagihan dilakukan di sisi server berdasarkan penggunaan (usage) permintaan secara keseluruhan, terlepas dari apakah permintaan tersebut streaming atau tidak.

VIII. Kode Kesalahan Umum

HTTP Status	Arti	Saran Penanganan
400	Parameter permintaan tidak valid	Perbaiki body permintaan sesuai pesan respon
401	Kunci API tidak ada atau tidak valid	Periksa header Authorization / x-api-key
403	Kunci dinonaktifkan, saldo habis, atau tidak berizin	Isi saldo, periksa status kunci, atau sesuaikan otorisasi
404	Model tidak ditemukan	Gunakan GET /v1/models untuk melihat model yang tersedia
429	Terlalu banyak permintaan (limit terlampaui)	Tunggu sejenak dan coba kembali (exponential backoff)
500	Kesalahan internal server	Coba lagi nanti; jika gagal terus, hubungi CS

Body respon kesalahan seragam dalam struktur {"code": status_code, "message": "deskripsi_error", "data": null}.

IX. Penggunaan dan Saldo

• Setiap panggilan akan dipotong saldo secara real-time berdasarkan penggunaan token × harga satuan model × multiplier rute. Harga dan rute dapat dilihat di GET /v1/models.
• Setelah masuk, Anda dapat melihat riwayat panggilan (model, token, biaya, status) di "Pusat Pengguna → Riwayat Penggunaan".
• Jika saldo tidak mencukupi, panggilan akan mengembalikan status 403, dan akan pulih segera setelah pengisian saldo.