API belgeleri — Zoneus Cloud

Kimlik doğrulama

Konsoldaki API anahtarları sayfasından bir anahtar oluştur ve her isteğe Authorization başlığıyla ekle. Anahtarı yalnız sunucunda sakla.

Authorization: Bearer zsc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Kredi ve sınırlar

1 kredi = $0,01. Yapay zeka kontrolü şarkı başına 0,2 kredi.
Her ay 500 ücretsiz kredi (Zoneus abonelerine 1.500) önce harcanır.
Başarısız istekler ücretlendirilmez; ücret alınmışsa otomatik iade edilir.
Dakikada 30 istek; hesabına kredi yüklediysen 120. Sınır aşılırsa 429 döner.
Dosya en fazla 60 MB olabilir.

Yapay zeka kontrolü

POST/v1/ai/detect

Bir şarkının yapay zekayla üretilip üretilmediğini ve hangi araçla yapıldığını döndürür. Önce dosyaya gömülü üretici kayıtları (C2PA, SynthID, etiketler) okunur; bulunursa sonuç kesindir. Ardından frekans izi analiz edilir.

Parametreler (multipart/form-data)

Alan	Açıklama
`audio`	Ses dosyası. Üreticiden indirilen ilk dosyayı gönder (WAV, MP3, M4A…); yeniden kaydedilen dosyalarda etiketler silinmiş olabilir. Ek teknik ölçüm (frekans sınırı) yalnız WAV'da yapılır.
`audio_url`	`audio` yerine herkese açık bir http(s) adresi.

Örnek

curl -X POST https://cloud.zoneus.net/v1/ai/detect \
  -H "Authorization: Bearer zsc_live_…" \
  -F "audio=@sarki.wav"

# Python
import requests
r = requests.post("https://cloud.zoneus.net/v1/ai/detect",
    headers={"Authorization": "Bearer zsc_live_…"},
    files={"audio": open("sarki.wav", "rb")})
print(r.json()["verdict"])

Yanıt

{
  "ok": true,
  "verdict": "ai",
  "certainty": "high",
  "ai_probability": 88,
  "generator": "Suno",
  "generators": [{ "name": "Suno", "score": 74 }],
  "provenance": { "found": false, "generator": "", "evidence": [], "method": "" },
  "signal": { "ok": true, "sample_rate": 48000, "duration": 182.4, "windows": 240, "cutoff_hz": 20100, "ai_score": 88 },
  "reasons": ["Dosyada üretici kaydı (C2PA, SynthID, etiket) bulunamadı.", "…"],
  "ms": 4210,
  "cost": { "credits": 0.2, "free_credits_used": 0.2 },
  "balance": { "free_credits": 499.8, "credits": 0 },
  "request_id": "zsc_…"
}

Alan	Anlamı
`verdict`	`ai` yapay zeka üretimi · `no_ai_found` yapay zeka izi bulunamadı · `unknown` karar verilemedi
`certainty`	`definitive` dosyadaki üretici kaydı · `high` / `medium` / `low` sinir ağı güven düzeyi
`ai_probability`	0–100 arası yapay zeka olasılığı
`generator`	Tespit edilen araç (ör. `Suno`, `Gemini`); emin olunamıyorsa `null`
`generators`	Aday araçlar ve benzerlik puanları
`provenance`	Dosyada bulunan köken kanıtı ve yöntemi
`signal`	Frekans analizinin teknik bilgileri; `cutoff_hz` düşükse dosya daha önce sıkıştırılmış olabilir
`reasons`	Sonucun gerekçeleri, okunabilir Türkçe cümlelerle

Hesap bilgisi

GET/v1/me

Bakiye, aylık ücretsiz kredi, dakikalık sınır ve fiyatları döndürür.

Modül listesi

GET/v1/modules

Etkin modülleri ve uç noktalarını döndürür.

Kullanım

GET/v1/usage?limit=100

Son isteklerin listesi: uç nokta, harcanan kredi, HTTP kodu, süre ve özet.

Hatalar

{ "ok": false, "error": { "code": "insufficient_credits", "message": "Kredin yetersiz…" }, "request_id": "zsc_…" }

HTTP · kod	Ne zaman
401 `missing_key` / `invalid_key`	Anahtar yok, hatalı ya da iptal edilmiş
400 `missing_audio`	`audio` ya da `audio_url` gönderilmedi
402 `insufficient_credits`	Yeterli kredi yok
413 `file_too_large`	Dosya 60 MB'tan büyük
422 `processing_failed`	Dosya çözülemedi ya da çok kısa (ücret iade edilir)
429 `rate_limited`	Dakikalık istek sınırı aşıldı