Dokumentasi

Dokumentasi

API manajemen

Kunci manajemen memungkinkan sistem Anda sendiri membuat, mengelompokkan, membatasi, dan mencabut kunci API di akun Anda, serta membaca biaya yang dikeluarkannya lewat API. Kunci ini tidak bisa memanggil model.

Untuk apa

Sebagian integrasi memberi setiap pelanggan, tim, atau penggunanya kunci API tersendiri, memasukkan kunci tiap pelanggan ke dalam grup, membatasi berapa yang boleh dibelanjakan satu grup, lalu membaca biayanya per kunci atau per grup. Di halaman Kunci API, cara itu cukup untuk beberapa kunci. Untuk jumlah lebih banyak, kunci manajemen memungkinkan skrip atau alat admin Anda sendiri melakukan hal yang sama lewat API.

Kunci manajemen adalah kredensial yang berbeda dari kunci API. Kunci ini tidak diterima di tempat kunci API diterima: tidak bisa memanggil /v1/chat/completions, /v1/messages, atau rute model lainnya. Kunci ini hanya berfungsi di /v1/management/, dan kunci API tidak berfungsi di sana.

Buat kunci manajemen

  • Buka halaman Kunci API dan gulir ke bagian bawah. Di bawah Kunci manajemen, pilih “Kunci manajemen baru”. Bagian ini tetap terlipat sampai Anda membukanya.
  • Beri kunci nama, misalnya billing sync, agar halaman dapat menunjukkan program mana yang membuat tiap perubahan.
  • Masukkan alamat yang boleh memanggilnya, satu per baris: satu alamat seperti 203.0.113.7, atau rentang seperti 203.0.113.0/24. Tanpa daftar IP yang diizinkan, siapa pun yang memegang kunci dapat menggunakannya, dan dialog akan memperingatkan Anda jika daftar dibiarkan kosong.
  • Salin kunci saat ditampilkan. Kunci hanya ditampilkan sekali: Kunavo hanya menyimpan hash-nya.

Satu akun dapat memiliki dua kunci manajemen aktif sekaligus. Cabut salah satunya untuk memberi ruang bagi yang lain.

Memanggilnya

Kirim kunci sebagai token Bearer ke https://api.kunavo.com/v1/management. Kunci manajemen tidak diterima dari browser: respons-nya tidak memuat header CORS, sehingga halaman di situs lain tidak dapat memanggilnya. Kunci ditempatkan di server Anda, jangan pernah di kode front-end.

curl https://api.kunavo.com/v1/management/groups \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"

Respons berupa JSON. Kesalahan memiliki bentuk yang sama dengan API lainnya: objek error dengan message, type, code, dan, jika relevan, param yang salah. Berikut status yang akan Anda temui:

StatusArtinya
401Kunci tidak ada, salah ketik, atau sudah dicabut, atau akunnya ditangguhkan atau sedang ditinjau.
403Kunci memiliki daftar IP yang diizinkan dan permintaan datang dari alamat yang tidak ada di dalamnya.
404Grup atau kunci tidak ada, sudah dihapus, atau milik akun lain. Ketiganya dijawab sama, sehingga ID dari akun lain tidak mengungkap apa pun.
409Perubahan bertentangan dengan keadaan akun: nama grup yang sudah dipakai, kunci yang sudah dicabut, atau akun yang sudah mencapai batas 500 kunci aktif.
429Kunci ini telah membuat 60 permintaan dalam satu menit terakhir. Header Retry-After menyebutkan berapa detik yang harus ditunggu.

Grup

GET /v1/management/groups mencantumkan grup akun, lengkap dengan batas bulanan masing-masing dan jumlah kunci aktif di dalamnya. POST membuat grup, dengan monthly_limit_usd opsional; nama yang sudah dipakai menghasilkan 409. PATCH /v1/management/groups/{id} mengubah nama atau batas: kirim null untuk tanpa batas, dan 0 untuk menjeda semua kunci dalam grup tanpa mencabut satu pun. DELETE menghapus grup, dan panggilannya tetap memakai nama grup itu di halaman Penggunaan. Kuncinya tetap aktif dan menjadi tanpa grup, kecuali Anda menambahkan ?revoke_keys=true, yang mencabutnya juga.

curl https://api.kunavo.com/v1/management/groups \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CID000001", "monthly_limit_usd": 50}'

Kunci

GET /v1/management/keys mencantumkan kunci, yang terbaru lebih dulu. Satu halaman berisi 50 kunci, dan limit menaikkannya menjadi 100. status secara bawaan active, atau revoked atau all, dan group_id mempersempit daftar ke satu grup. Jika has_more bernilai true, kirim next_after sebagai after untuk membaca halaman berikutnya. Teks asli kunci tidak pernah dicantumkan.

POST /v1/management/keys membuat kunci dengan nama dan, secara opsional, group_id, monthly_limit_usd, dan ip_allowlist. Respons memuat teks asli kunci di kolom key, hanya sekali. POST yang diulang membuat kunci kedua, jadi sebelum mencoba ulang, daftar kunci dan cari namanya.

curl https://api.kunavo.com/v1/management/keys \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CID000001_user1", "group_id": "GROUP_ID", "monthly_limit_usd": 20}'

PATCH /v1/management/keys/{id} mengubah nama, grup, batas, atau daftar yang diizinkan sebuah kunci; group_id bernilai null mengeluarkannya dari grupnya. DELETE mencabutnya. Mencabut kunci yang sudah dicabut bukan kesalahan. Kunci yang sudah dicabut tidak dapat diubah.

curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"

Penggunaan

GET /v1/management/usage melaporkan penggunaan seluruh akun selama maksimal 90 hari UTC, sebagaimana GET /v1/usage melaporkan satu kunci. group_by menerima kombinasi apa pun dari group, api_key, model, dan day, dengan bawaan api_key. Angkanya bermakna sama seperti di halaman Penggunaan: panggilan dihitung di grup tempat kuncinya berada saat panggilan dibuat, panggilan yang gagal tidak dikenai biaya, dan total suatu periode sama persis dengan ekspor CSV untuk hari yang sama hingga sen terakhir. group_id dan api_key_id mempersempit laporan ke satu grup atau satu kunci.

curl "https://api.kunavo.com/v1/management/usage?start_date=2026-10-01&end_date=2026-10-31&group_by=group,api_key" \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"
Tanggal adalah hari kalender UTC, kedua ujungnya disertakan. end_date setelah hari ini dibaca sebagai hari ini, dan respons menyertakan tanggal akhir yang dipakai.

Jaga keamanannya

  • Tetapkan daftar IP yang diizinkan. Kunci yang hanya berfungsi dari alamat server Anda hampir tidak berguna bagi orang yang mencurinya.
  • Simpan kunci di penyimpanan rahasia pada server yang menjalankan alat Anda. Jangan pernah menaruhnya di browser, aplikasi seluler, atau repositori.
  • Jika bocor, cabut di bagian bawah halaman Kunci API, atau dengan DELETE pada kunci itu. Dialog pencabutan juga dapat mencabut kunci yang dibuat oleh kunci tersebut.
  • Setiap perubahan yang dibuat kunci lewat API tercantum di bawah Kunci manajemen pada halaman Kunci API, lengkap dengan waktu, alamat asal, dan kunci yang membuatnya: 50 perubahan terakhir. Perubahan yang dibuat secara manual di halaman itu tidak tercantum.
  • Kunci berhenti berfungsi dengan sendirinya saat akunnya ditangguhkan atau sedang ditinjau, dan saat kunci dicabut.

Satu kunci manajemen boleh membuat 60 permintaan per menit. Buat satu permintaan untuk setiap perubahan, dan baca daftar per halaman, bukan kunci demi kunci.

Grup, batas bulanannya, dan cara angkanya dihitung dijelaskan di halaman grup kunci. Angka penggunaannya sama dengan di halaman Penggunaan.