Dokümantasyon

Dokümantasyon

Anahtar grupları

Her müşterinize kendi API anahtarlarını verin, bunları bir grupta toplayın, her müşterinin ve her anahtarın istediğiniz herhangi bir dönemde ne kadar harcadığını görün ve her müşterinin bir ayda harcayabileceği tutarı sınırlayın. Tek hesap, tek bakiye.

Grup, hesabınızdaki bir API anahtarı klasörüdür; örneğin her müşteri için bir tane: CID000001, CID000002. Gruptaki bir anahtar API'yi diğer anahtarlar gibi çağırır ve grubun kendine ait bakiyesi, bakiye yüklemesi veya oturum açma özelliği yoktur; grubun tüm anahtarları için toplam bir aylık harcama sınırı olabilir. Bir anahtar tek bir gruba aittir ya da hiçbir gruba ait değildir.

Grupları üç adımda kurun

  • Bir grup oluşturun. API anahtarları sayfasında “Yeni grup” seçeneğini seçin ve gruba müşterinin adını verin.
  • Anahtarları gruba ekleyin. Grup içinde anahtar oluşturmak için grubun başlığındaki “Yeni anahtar” seçeneğini seçin. Mevcut bir anahtarı gruba koymak için anahtarın menüsünü açıp “Gruba taşı” seçeneğini seçin.
  • Rakamları okuyun. API anahtarları sayfası, her anahtarın bu takvim ayında harcadığı tutarı ve her grubun toplamını gösterir. Kullanım sayfası aynı anahtarları grupları altında bugün, son 7 veya 30 gün, bu ay, geçen ay ya da seçtiğiniz günler (en fazla 90 gün) için gösterir.

Bir ayı okuyun ve dışa aktarın

Kullanım sayfasının üstünde “Geçen ay” (veya “Bu ay”, ya da gün seçmek için “Özel”) seçeneğini seçin. “API anahtarına göre” bölümünde her grubun başlığı, grubun maliyetini ve çağrı sayısını gösterir. Üstteki grup menüsü tüm sayfayı tek bir grupla sınırlar: rakamları, grafiği, modelleri ve çağrıları. “CSV dışa aktar”, sayfanın gösterdiği içeriği aynı dönem ve aynı grupla, anahtara göre ya da güne göre indirir.

Anahtara göre dosyada her anahtar ve grup için bir satır bulunur ve dosya adı kunavo-cost-by-key_2026-10-01_2026-10-31.csv biçimindedir. Dosya, dönem içinde çağrı yapan her anahtarı (iptal edilenler dahil) her çağrının yapıldığı grubun altında, şu anki grubunda çağrısı olmayan her etkin anahtarı da 0 ile listeler; böylece her müşterinin anahtar listesi eksiksiz olur. Gruplar panodaki sırayla, her grubun anahtarları en pahalıdan en ucuza, grupsuz anahtarlar en sonda yer alır. Güne göre dosyada önce bir date sütunu bulunur ve bir anahtarın bir grupta çağrı yaptığı her gün için bir satır vardır.

Sütunİçeriği
groupÇağrıların yapıldığı grup; hiçbir grupta yapılmayan çağrılar için boştur. Daha sonra silinen bir grubun adının ardından (deleted) gelir.
key_nameAnahtarın adı.
key_prefixPanoda gösterildiği şekliyle anahtarın başı. Asla anahtarın tamamı değil.
key_statusactive veya revoked.
callsAralıkta anahtarla yapılan çağrılar.
errorsBu çağrılardan başarısız olanlar. Başarısız bir çağrı ücretlendirilmez.
input_tokensGirdi token'ları; önbellek okumaları ve yazmaları dahil.
output_tokensÇıktı token'ları.
cached_input_tokensGirdi token'larından istem önbelleğinden okunanlar.
cache_write_tokensGirdi token'larından istem önbelleğine yazılanlar.
cost_usdÇağrılar için alınan ücret; ABD doları cinsinden, sekiz ondalık basamakla.
Formüle benzeyen adlar. =, +, - veya @ ile başlayan bir grup ya da anahtar adı başına kesme işareti eklenerek yazılır; böylece elektronik tablo onu formül olarak çalıştırmak yerine metin olarak gösterir.

Her grubun bir ayda harcadığını sınırlayın

API anahtarları sayfasında bir grubun menüsünü açın ve “Aylık sınır belirle” seçeneğini seçin. Sınır, grubun tüm anahtarlarının bir takvim ayında (UTC) birlikte harcadığı tutarı, yani her anahtarın grupta bulunduğu sırada yaptığı çağrıları sayar. Grubu sınırın üzerine çıkaracak bir istek 402 ile reddedilir ve bu istek için ücret alınmaz. Sınır koymamak için alanı boş bırakın ya da hiçbir anahtarı iptal etmeden gruptaki tüm anahtarları duraklatmak için 0 girin.

Bir anahtarın kendi aylık sınırı da geçerli olmaya devam eder ve önce hangi sınıra ulaşılırsa istek o sınırla reddedilir. Grubun başlığı, ayın harcamasını sınıra göre gösterir; istekler reddedilmeye başlayınca “Sınıra ulaşıldı”, sınır 0 olduğunda “Duraklatıldı” yazar.

Bir grup ya da kendi sınırı olan bir anahtar aylık sınırının %80'ini kullandığında Kunavo hesabınızın e-posta adresine yazar; bu sınır nedeniyle istekler reddedilmeye başladığında bir kez daha yazar. Her sınır için her türden en fazla ayda bir e-posta gönderilir.

Tutarlar nasıl sayılır

  • Maliyet, alınan ücrettir. Her çağrının maliyeti, çağrı tamamlandığında bakiyenizden düşülen tutardır. Başarısız bir çağrı ücretlendirilmez.
  • Aylar ve günler UTC'dir. Bu ay, ayın 1'inde 00:00 UTC'de başlar. Örneğin Yangon'da (UTC+6:30) ekim ayı, yerel saatle 1 Kasım 06:30'da biter. Kullanım sayfası gösterdiği aralığın tarihlerini yazar.
  • Bir çağrı, yapıldığı sırada anahtarının bulunduğu grupta sayılır. Bir anahtarı başka bir gruba taşırsanız orada yalnızca o andan sonraki çağrıları sayılır; önceki çağrıları oldukları yerde kalır. Bu yüzden API anahtarları sayfasında bir grubun aylık toplamı, şu anda altında listelenen anahtarların toplamından farklı olabilir.
  • İptal edilmiş bir anahtar grubunda kalır. İptal edilmeden önce harcadığı tutar o grubun toplamlarında sayılmaya devam eder ve dışa aktarımda görünür.
  • Silinen bir grup çağrılarını korur. Bu çağrılar Kullanım sayfasında ve dışa aktarmada grubun adı altında, silindi olarak işaretlenmiş şekilde kalır; ad yeni bir grup için yeniden kullanılabilir.
  • Üç yer, tek rakam. Aynı takvim ayı için bir grubun API anahtarları sayfasındaki toplamı, Kullanım sayfasında “Bu ay” altındaki toplamı ve CSV'deki satırlarının toplamı sentine kadar aynıdır.

Sorular

  • Her grubun kendi bakiyesi var mı? Hayır. Tüm gruplar hesabınızın tek bakiyesini kullanır. Bir müşterinin harcayabileceğini sınırlamak için o müşterinin grubuna ya da her anahtarına aylık bir sınır koyun.
  • Müşterilerim oturum açıp kullanımlarını görebilir mi? Hayır. Grupları yalnızca siz görebilirsiniz. Bir anahtar kendi kullanımını GET /v1/usage ile okuyabilir; bu yanıt anahtarın grubunu göstermez. Anahtarın grubunun aylık sınırı varsa GET /v1/balance, anahtara bu sınırı ve tüm grubun bu ay harcadığı tutarı gösterir, ancak grubun adını göstermez.
  • Bir grubu silersem ne olur? Siz seçersiniz: grubun anahtarları çalışmaya devam eder ve o andan sonra grupsuz olur ya da grupla birlikte iptal edilir. Her iki durumda da anahtarların yaptığı çağrılar grubun adı altında kalır.
  • Bir anahtar bir müşteriden başka bir müşteriye geçerse ne olur? Anahtarı diğer müşterinin grubuna taşıyın: o andan sonraki çağrıları orada sayılır, önceki çağrıları ise ilk müşteride kalır.
  • Başka dönemleri de okuyabilir miyim? Evet: Kullanım sayfasında “Özel” seçeneğini seçip en fazla 90 gün belirleyin. Bir program için GET /v1/usage, aynı dönemde bir anahtarın günlük maliyetini döndürür.

Bir müşterinin anahtarlarını elle değil kendi araçlarınızla oluşturmak, gruplamak, sınırlamak ve iptal etmek için yönetim API’sini kullanın. Anahtarları ayrı bir kimlik bilgisidir ve yalnızca o API üzerinde çalışır.