API genel bakış

Her CID222 API yüzeyi, yanıt verdiği temel yol, kabul ettiği kimlik bilgisi ve döndürdüğü biçim.

Temel URL

Genel bir rota öneki yoktur. Her denetleyici kendi temel yolunu tanımlar ve yollar tekbiçimli değildir — /api/v1 altındaki tek yüzey tespittir.

https://<appliance-fqdn>

Ağ geçidi TCP 3000 üzerinde 0.0.0.0 adresine bağlı olarak dinler; bir cihaz bunu kendi TLS katmanının arkasında 443 üzerinden yayımlar. Üretimde https://<appliance-fqdn> kullanın; http://localhost:3000 yalnızca konteynere doğrudan çağrı yaparken geçerlidir.

Kimlik doğrulama

Kimlik doğrulamalı her istek bir bearer token taşır. CID222 iki kimlik bilgisi türünü cid_key_ önekinden ayırt eder.

# Ağ geçidi API anahtarı (sunucudan sunucuya)
Authorization: Bearer cid_key_0123456789abcdef…

# Kullanıcı JWT'si (POST /auth/login ile alınır)
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

Sohbet uç noktaları

Tespit ve dosya uç noktaları

Oturum uç noktaları

Kimlik doğrulama uç noktaları

İstek biçimi

İstekler Content-Type: application/json başlığıyla JSON'dur. "Hiçbir şey yapmayan" bir isteği ayıklamadan önce bilinmesi gereken iki davranış vardır:

• Bilinmeyen alanlar reddedilmez, temizlenir. Doğrulama beyaz liste ile çalışır; uç noktanın tanımlamadığı bir gövde alanı sessizce kaldırılır ve istek devam eder. Yanlış yazılmış bir parametre, varsayılan davranışla başarılı bir çağrı üretir.
• Gövde sınırı 50 MB'dir (JSON ve URL kodlu gövdeler için). Görüntü analizi, çözülmüş görüntüyü bu sınırdan bağımsız olarak 10 MB ile; belge analizi ise yüklemeyi 20 MB ile sınırlar.

Yanıt biçimi

İki akış uç noktası ayrıca Cache-Control: no-cache, Connection: keep-alive ve X-Accel-Buffering: no başlıklarını gönderir.

Bir SSE yanıtı, her biri tek bir JSON nesnesi taşıyan data: satırlarından oluşur ve data: [DONE] ile sonlanır:

data: {"type":"token_usage","usage":{"prompt_tokens":20,"completion_tokens":10,"total_tokens":30}}

data: {"id":"filtered-response","content":"Hello. How can I help?","finish_reason":"stop","filtered":false,"entities_masked":0}

data: [DONE]

Hız sınırları

Hız sınırlama yalnızca kimlik doğrulaması gerektirmeyen oturum açma yüzeylerinde vardır ve istemci IP adresine göre anahtarlanır.

POST /chat/completions ve POST /api/v1/guardrails/detect dahil diğer her uç nokta sınırsızdır. CID222 hiçbir yanıtta X-RateLimit-Limit, X-RateLimit-Remaining veya X-RateLimit-Reset başlığı göndermez ve katman başına istek veya token kotası yoktur. Sağlayıcı harcamasını bir ağ geçidi kotasıyla değil, Token Maliyeti ve Tasarruf ile bütçeleyin.

Sayfalama

Sayfalama yalnızca yönetim liste uç noktaları için geçerlidir — GET /admin/api-keys, GET /admin/models ve benzerleri. GET /sessions ve sohbet yüzeyi eksiksiz sonuç döndürür.

Sorgu parametreleri page (varsayılan 1) ve limit'tir (varsayılan 10):

{
  "data": [],
  "meta": { "total": 42, "page": 1, "limit": 10, "totalPages": 5 }
}

Hatalar

Hata gövdesi tekbiçimli değildir. CID222 politika reddi makine tarafından okunabilir bir code taşır; çerçeve düzeyindeki bir reddetme taşımaz. Önce HTTP durum koduna bakın.

{
  "statusCode": 400,
  "message": "Invalid request body",
  "error": "Bad Request"
}

{
  "statusCode": 403,
  "code": "FEATURE_NOT_LICENSED",
  "message": "This feature is not included in the installed license tier.",
  "feature": "documents",
  "tier": "starter"
}

İçerik engellemeleri HTTP hatası değildir. /chat/completions üzerinde engellenmiş bir istem veya yanıt, 200 yanıtı içinde bir SSE olayı olarak gelir; yalnızca durum koduna bakan bir istemci başarı görür. Akışı okuyun.

Notlar

• Yalnızca tespit /api/v1 altındadır. Önek yalnızca o denetleyiciye gömülüdür. Bunu genel bir sürüm öneki sanmak diğer her yerde 404 üretir.
• POST /api/v1/guardrails/detect, POST olmasına rağmen 201 değil 200 döndürür.
• Tespit hiçbir zaman ham KKV döndürmez. detectedEntities[].value bir yer tutucu veya [REDACTED]'tır ve normalization.originalText kasıtlı olarak boştur.
• Geri döngü veya özel adresten gelen kimlik doğrulamasız bir tespit çağrısı kiracı bağlamı olmadan kabul edilir. Bu, küme içindeki kırmızı takım servisi içindir. Diğer her çağıranın bir kimlik bilgisine ihtiyacı vardır.

İlgili

• Sohbet API'si — istek gövdesi ve SSE olay sözleşmesinin tamamı.
• Oturumlar API'si — sunucu tarafında konuşma durumu, yalnızca JWT.
• Kimlik doğrulama — anahtar oluşturma ve token alma.