Dokümantasyon
Yönetim API'si
Bir yönetim anahtarı, kendi sistemlerinizin hesabınızdaki API anahtarlarını oluşturmasına, gruplamasına, sınırlamasına ve iptal etmesine, ayrıca anahtarların ne harcadığını API üzerinden okumasına olanak tanır. Model çağıramaz.
Ne işe yarar
Bazı entegrasyonlar müşterilerinin, ekiplerinin veya kullanıcılarının her birine kendi API anahtarını verir, her müşterinin anahtarlarını bir gruba koyar, bir grubun harcayabileceği tutarı sınırlar ve maliyeti anahtara ya da gruba göre geri okur. API anahtarları sayfasında bu, birkaç anahtar için yeterlidir. Daha fazlası için yönetim anahtarı, bir betiğin veya kendi yönetim aracınızın aynı işleri API üzerinden yapmasını sağlar.
Yönetim anahtarı, API anahtarından farklı bir kimlik bilgisidir. API anahtarının kabul edildiği yerlerde kabul edilmez: /v1/chat/completions, /v1/messages veya başka herhangi bir model rotasını çağıramaz. Yalnızca /v1/management/ üzerinde çalışır ve API anahtarı orada çalışmaz.
Yönetim anahtarı oluşturun
- API anahtarları sayfasını açın ve en altına inin. Yönetim anahtarları bölümünde “Yeni yönetim anahtarı” seçeneğini seçin. Bölüm, siz açana kadar katlı kalır.
- Anahtara bir ad verin, örneğin billing sync; böylece sayfa her değişikliği hangi programın yaptığını gösterebilir.
- Anahtarın çağrılabileceği adresleri her satıra bir tane olmak üzere girin: 203.0.113.7 gibi tek bir adres ya da 203.0.113.0/24 gibi bir aralık. İzin listesi yoksa anahtara sahip olan herkes onu kullanabilir; listeyi boş bırakırsanız iletişim kutusu sizi uyarır.
- Anahtar gösterildiğinde kopyalayın. Yalnızca bir kez gösterilir: Kunavo yalnızca hash'ini saklar.
Bir hesapta aynı anda en fazla iki etkin yönetim anahtarı olabilir. Başka birine yer açmak için birini iptal edin.
Çağırma
Anahtarı https://api.kunavo.com/v1/management adresine Bearer token olarak gönderin. Yönetim anahtarları tarayıcıdan kabul edilmez: yanıtlarında CORS başlıkları yoktur, bu yüzden başka bir sitedeki bir sayfa onları çağıramaz. Anahtarın yeri sunucunuzdur, ön yüz kodu asla değil.
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"Yanıtlar JSON biçimindedir. Hatalar API'nin geri kalanıyla aynı yapıdadır: bir error nesnesi; içinde message, type, code ve geçerliyse hatalı olan param bulunur. Karşılaşacağınız durum kodları şunlardır:
| Durum | Anlamı |
|---|---|
401 | Anahtar eksik, yanlış yazılmış veya iptal edilmiş ya da hesabı askıya alınmış veya incelemede. |
403 | Anahtarın bir IP izin listesi var ve istek listede olmayan bir adresten geldi. |
404 | Grup veya anahtar yok, silinmiş ya da başka bir hesaba ait. Üçü de aynı yanıtı verir; böylece başka bir hesaptan bir kimlik hiçbir şey ele vermez. |
409 | Değişiklik hesabın durumuyla çakışıyor: kullanımda olan bir grup adı, iptal edilmiş bir anahtar ya da 500 etkin anahtarlık üst sınıra ulaşmış bir hesap. |
429 | Bu anahtar son bir dakikada 60 istek yaptı. Retry-After başlığı kaç saniye bekleneceğini söyler. |
Gruplar
GET /v1/management/groups hesabın gruplarını, her birinin aylık sınırı ve kaç etkin anahtar içerdiğiyle birlikte listeler. POST bir grup oluşturur, isteğe bağlı olarak monthly_limit_usd ile; kullanımda olan bir ad 409 döndürür. PATCH /v1/management/groups/{id} adı veya sınırı değiştirir: sınırsız için null, grubun hiçbir anahtarını iptal etmeden tümünü duraklatmak için 0 gönderin. DELETE bir grubu kaldırır; çağrıları Kullanım sayfasında grubun adıyla kalır. Anahtarları etkin kalır ve gruptan çıkar, ancak ?revoke_keys=true eklerseniz onlar da iptal edilir.
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}'Anahtarlar
GET /v1/management/keys anahtarları en yeniden eskiye listeler. Bir sayfada 50 anahtar bulunur, limit bunu 100’e çıkarır. status varsayılan olarak active, ya da revoked veya all olabilir; group_id listeyi tek bir gruba daraltır. has_more true olduğunda sonraki sayfayı okumak için next_after değerini after olarak iletin. Bir anahtarın düz metni asla listelenmez.
POST /v1/management/keys bir ad ve isteğe bağlı olarak group_id, monthly_limit_usd ve ip_allowlist ile anahtar oluşturur. Yanıt düz metni key alanında, yalnızca bir kez verir. Tekrarlanan bir POST ikinci bir anahtar oluşturur; bu yüzden birini yeniden denemeden önce anahtarları listeleyip adını arayın.
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} bir anahtarın adını, grubunu, sınırını veya izin listesini değiştirir; group_id değeri null olursa anahtar grubundan çıkar. DELETE onu iptal eder. Zaten iptal edilmiş bir anahtarı iptal etmek hata değildir. İptal edilmiş bir anahtar değiştirilemez.
curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"Kullanım
GET /v1/management/usage tüm hesabın kullanımını en fazla 90 UTC günü için raporlar, GET /v1/usage ise tek bir anahtarınkini. group_by, group, api_key, model ve day değerlerinin herhangi bir karışımını kabul eder; varsayılanı api_key. Rakamlar Kullanım sayfasındakiyle aynı anlama gelir: bir çağrı, yapıldığı sırada anahtarının bulunduğu grupta sayılır, başarısız çağrı ücret almaz ve bir dönemin toplamı, aynı günlerin CSV dışa aktarımıyla sentine kadar eşittir. group_id ve api_key_id raporu tek bir gruba veya tek bir anahtara daraltır.
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"end_date bugün olarak okunur ve yanıt kullandığı bitiş tarihini yansıtır.Güvende tutun
- Bir izin listesi belirleyin. Yalnızca sunucunuzun adreslerinden çalışan bir anahtar, onu çalan biri için pek değer taşımaz.
- Anahtarı, aracınızı çalıştıran sunucudaki bir gizli bilgi deposunda saklayın. Asla tarayıcıya, mobil uygulamaya veya kod deposuna koymayın.
- Sızarsa API anahtarları sayfasının en altından ya da üzerinde
DELETEile iptal edin. İptal iletişim kutusu, o anahtarın oluşturduğu anahtarları da iptal edebilir. - Anahtarın API üzerinden yaptığı her değişiklik, API anahtarları sayfasındaki Yönetim anahtarları bölümünde zamanı, geldiği adres ve değişikliği yapan anahtarla birlikte listelenir: son 50 değişiklik. O sayfada elle yapılan değişiklikler listelenmez.
- Bir anahtar, hesabı askıya alındığında ya da incelemeye alındığında ve iptal edildiğinde kendiliğinden çalışmayı durdurur.
Bir yönetim anahtarı dakikada 60 istek yapabilir. Her değişiklik için tek istek yapın ve bir listeyi anahtar anahtar değil, sayfa sayfa okuyun.
İlgili sayfalar
Grupları, aylık sınırlarını ve rakamlarının nasıl sayıldığını anahtar grupları sayfası açıklar. Kullanım rakamları Kullanım sayfasındakiyle aynıdır.