Dokümantasyon

Kimlik doğrulama

Kunavo, OpenAI ile aynı şekilde kimlik doğrular: Authorization başlığında tek bir bearer belirteci kullanır. Tipik bir OpenAI entegrasyonundan tek fark temel URL'dir.

Her API çağrısı https://api.kunavo.com/v1 adresine Authorization: Bearer sk-kn-XXX ile gider. Hepsi bu.

Temel URL

Her modeli ve her kipliği karşılayan tek uç nokta.

Alan	Değer
Temel URL	`https://api.kunavo.com/v1`
Bölge	Birincil bölge ABD (Ashburn), çok bölgeli uç katmanı yönlendirmesi
TLS	TLS 1.2+ zorunludur. Yalnızca HTTPS kullanılır.

Yol düzeni OpenAI kurallarını izler:

Modalite	Yol
Sohbet	`POST /v1/chat/completions`
Modelleri listele	`GET /v1/models`
Görüntü oluşturma	`POST /v1/images/generations`
Görsel düzenleme / i2i	`POST /v1/images/edits`
Video oluşturma	`POST /v1/video/generations`
TTS	`POST /v1/audio/speech`
Müzik	`POST /v1/audio/music`

API anahtarları

API anahtarları, kontrol panelinde /app/keys'den oluşturulur. Her anahtar:

sk-kn- ile başlar ve ardından en az 30 rastgele karakter gelir.
Oluşturulurken yalnızca bir kez gösterilir — Kunavo sonrasında yalnızca bir karmasını saklar.
Kontrol panelinde kullanılan, insanlarca okunabilir bir adı vardır (ör. prod-web).
İstediğiniz zaman iptal edilebilir — iptalden hemen sonra anahtar 401 yanıtı verir.
Her anahtarın kendine ait aylık harcama limiti ve IP izin listesi olabilir. İkisi de /app/keys'den ayarlanır ve her çağrıda uygulanır.

Anahtar başına harcama limitleri (isteğe bağlı)

Her anahtar için dolar cinsinden aylık harcama limiti belirleyebilirsiniz. İlgili anahtarın geçerli takvim ayındaki kesinleşmiş kullanımı limiti aşacaksa, limit ay başında sıfırlanana kadar bu anahtarla yapılan çağrılar 402 insufficient_quota yanıtı verir ve ücret alınmaz. Diğer anahtarlarınız etkilenmez — bu, hesabın değil tek bir kimlik bilgisinin üst sınırıdır.

Gözetimsiz bir ajanın gerçekten ihtiyaç duyduğu sınırlandırma budur: cüzdan bakiyesi tüm anahtarlar arasında ortaktır; bu nedenle tek başına, kontrolden çıkan bir döngünün tüm bakiyeyi harcamasını engelleyemez. Ajan için işin kapsamına uygun limitli ayrı bir anahtar oluşturun; böylece en kötü durum bu tutarla sınırlanır. $0 tutarındaki limit, anahtarı iptal etmeden duraklatır.

Anahtar başına IP izin listesi (isteğe bağlı)

Bir anahtar belirli adreslerle de sınırlandırılabilir. Her satıra bir IPv4/IPv6 adresi veya CIDR bloğu girin (203.0.113.7, 198.51.100.0/24, 2001:db8::/32); başka bir yerden bu anahtarla gelen çağrılar, /v1/models dahil tüm uç noktalarda 403 permission_error ile reddedilir. Her adresi kabul etmek için alanı boş bırakın.

Denetlediğimiz adres, istemcinin bir başlıkta bildirebileceği adres değil, uç proxy'mizin gözlemlediği adrestir; bu nedenle bir izin listesi X-Forwarded-For sahteciliğiyle aşılamaz. Bunun karşılığı şudur: izin listesi olan bir anahtar, çağıran taraf yeni bir makineye, NAT ağ geçidine veya ağa geçtiği anda çalışmayı durdurur. İzin listelerini dizüstü bilgisayarlara değil, dış bağlantılarında sabit çıkış adresleri kullanan sunuculara bağlayın.

İstek başlıkları

En basit istekte şu iki başlık bulunur:

Authorization: Bearer sk-kn-...
Content-Type: application/json

Her uç nokta, Authorization yerine Anthropic SDK'lerinin gönderdiği x-api-key başlığından da anahtarı okur. Böylece Anthropic API'si için oluşturulmuş bir istemci, özel başlık gerekmeden /v1/models dahil tüm rotalara erişir. İstek ikisini de içeriyorsa Authorization okunur. Anahtarın harcama limiti ve IP izin listesi, hangi başlıkla gönderildiğinden bağımsız olarak uygulanır.

İsteğe bağlı ama önerilir: uygulamanızı tanımlayan User-Agent. İstek kaynaklarında hata ayıklayabilmeniz için kullanıcı aracılarını /app/usage kontrol panelinize kaydederiz.

OpenAI SDK'sini kullanma

Ekiplerin çoğu resmi OpenAI SDK'sini kullanmayı sürdürür ve yalnızca base_url değerini değiştirir. Python (v1.x+) ve Node (v4.x+) sürümleri bu şekilde çalışır.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KUNAVO_API_KEY"],
    base_url="https://api.kunavo.com/v1",
)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KUNAVO_API_KEY,
  baseURL: "https://api.kunavo.com/v1",
});

OpenAI SDK'si Node'da baseURL, Python'da ise base_url kullanır. İkisi de aynı uç noktaya yönlendirilir.

Anahtarları yenileme

En iyi uygulama: API anahtarlarını üç ayda bir veya bir anahtarın sızmış olabileceği her durumda yenileyin. Kunavo, hesap başına aynı anda birden fazla anahtara izin verir; böylece yenileme, bir anda geçiş yapmak yerine eski ve yeni anahtarları birlikte kullanarak sorunsuz biçimde yapılır.

# 1. Create a new key in /app/keys, set its name to e.g. "prod-2026-Q2"
# 2. Deploy new key to your servers
# 3. Verify traffic is flowing on the new key (dashboard shows usage)
# 4. Revoke the old key from /app/keys → it 401s immediately

# In code, swap one env var:
export KUNAVO_API_KEY="sk-kn-new-..."

İptal edilen bir anahtar anında 401 yanıtı verir. Ek süre yoktur; eski anahtarı iptal etmeden önce trafiğin yeni anahtara geçtiğinden emin olun.

Güvenlik notları

Anahtarları istemci tarafında asla açığa çıkarmayın. Tarayıcı kodu ve mobil paketler herkese açıktır. İstekleri her zaman sunucunuz üzerinden iletin.
Anahtarları dar kapsamlı tutun. Her proje için farklı anahtarlar kullanmak, diğer iş yüklerini etkilemeden iptal olanağı sağlar. Ayrıca her anahtarın kendi harcama limiti ve IP izin listesi olabilir; böylece sızan bir anahtarın maliyeti ve kaynağı sınırlandırılır.
Kontrol panelini izleyin. /app/usage sayfasında trafik anahtara göre ayrılmış olarak gösterilir; beklenmedik etkinlikleri fark etmek kolaylaşır.
Şüpheli sızıntıları bildirin. E-posta gönderin: support@kunavo.com; anahtarları geçersiz kılma ve olay incelemesi konusunda yardımcı oluruz.