API Referansı

ozDNA REST API, production AI gateway'ini B2B entegrasyonlara açar. JSON istek/yanıt, Bearer token kimlik doğrulama ve OpenAPI 3.1 sözleşmesi. İstemci kütüphaneleri: SDK genel bakış (Python, Node.js, Go, Java).

Giriş

API, AI metin dedeksiyonu sunar — /v1/detect üzerinden segment düzeyinde analiz, dikey mod kalibrasyonu ve çok dilli destek. ozDNA metin humanizasyonu veya dedeksiyon atlatma araçları sunmaz.

Aynı production motoru tezmakale.com üzerinde çalışır; B2B API katmanı backend olgunlaştıkça açılmaktadır. Ayrıca: ozDNA production partner'ları · TezMakale vaka çalışması.

Kimlik doğrulama

Tüm isteklerde Bearer token ile Authorization header'ı zorunludur:

Authorization: Bearer ozdna_sk_live_...

API anahtarları dashboard üzerinden proje kapsamında oluşturulur. Anahtarlar ozdna_sk_test_ (sandbox) veya ozdna_sk_live_ (production) öneki ile gelir.

API anahtarlarını istemci tarafı kodda asla açığa çıkarmayın. İstekleri backend'iniz üzerinden yönlendirin veya ozDNA gateway proxy desenini kullanın.

Hızlı başlangıç

İlk API yanıtınızı üç adımda alın:

1. Erişim isteyin — Sandbox kimlik bilgileri için waitlist'e katılın.
2. API anahtarı oluşturun — Dashboard'da test anahtarı üretin (ozdna_sk_test_...).
3. Detect isteği gönderin — Bearer token ile metni /v1/detect endpoint'ine POST edin.

# 1. API anahtarınızı ayarlayın
export OZDNA_API_KEY="ozdna_sk_test_..."

# 2. AI üretimi metni tespit edin
curl -X POST https://api.sandbox.ozdna.com/v1/detect \
  -H "Authorization: Bearer $OZDNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Örnek akademik metin...", "mode": "academic", "language": "tr"}'

Base URL

https://api.ozdna.com          # production (beta)
https://api.sandbox.ozdna.com  # sandbox

cURL örneği

Header ve JSON gövdesi ile tam detect isteği:

curl -X POST https://api.ozdna.com/v1/detect \
  -H "Authorization: Bearer ozdna_sk_live_..." \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: $(uuidgen)" \
  -d '{
    "text": "Bu çalışmada uygulanan metodoloji...",
    "mode": "academic",
    "language": "tr"
  }'

Node.js SDK örneği

// npm install @ozdna/sdk  (yakında — şimdilik fetch kullanın)
const OZDNA_API_KEY = process.env.OZDNA_API_KEY;

async function detect(text) {
  const res = await fetch('https://api.ozdna.com/v1/detect', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${OZDNA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text,
      mode: 'academic',
      language: 'tr',
    }),
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`ozDNA ${res.status}: ${err.message}`);
  }

  return res.json();
}

detect('Analiz edilecek örnek metin...')
  .then(result => console.log(result.ai_probability))
  .catch(console.error);

Python SDK örneği

# pip install ozdna  (yakında — şimdilik requests kullanın)
import os
import requests

OZDNA_API_KEY = os.environ["OZDNA_API_KEY"]
BASE_URL = "https://api.ozdna.com"

def detect(text: str, mode: str = "academic", language: str = "tr") -> dict:
    response = requests.post(
        f"{BASE_URL}/v1/detect",
        headers={
            "Authorization": f"Bearer {OZDNA_API_KEY}",
            "Content-Type": "application/json",
        },
        json={"text": text, "mode": mode, "language": language},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = detect("Analiz edilecek örnek metin...")
    print(f"AI olasılığı: {result['ai_probability']}")

POST /v1/detect

{
  "ai_probability": 0.94,
  "confidence": "high",
  "verdict": "ai_generated",
  "segments": 12,
  "segment_map": [
    { "start": 0, "end": 142, "score": 0.97 }
  ],
  "processing_ms": 210,
  "mode": "academic",
  "language": "tr"
}

POST /v1/batch

LLM Gateway

Production AI gateway, OpenAI uyumlu inference route'larını tek giriş noktasından sunar. Her istek kimlik doğrulama, kota kontrolü, rate limit, model yönlendirme ve maliyet atamasından geçer. Yanıt header'ları: X-OzDNA-Model, X-OzDNA-Cost-USD, önbellekten gelen embeddings için X-OzDNA-Cache: HIT.

İsteğe bağlı mode alanı (academic, legal, financial, general) chat ve completion için model yönlendirmesini belirler.

POST /v1/chat

curl -X POST https://api.ozdna.com/v1/chat \
  -H "Authorization: Bearer $OZDNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "academic",
    "messages": [{ "role": "user", "content": "Token ekonomisini özetle." }]
  }'

POST /v1/completion

POST /v1/embeddings

POST /v1/rerank

POST /v1/moderation

Admin REST API

Otomasyon ve CI için programatik org yönetimi. Route'lar aynı organizasyona kapsamlı Bearer anahtar gerektirir. Anahtarlar org içinde kaynak oluşturabilir; tam secret yalnızca oluşturma anında döner.

Organizasyonlar

curl https://api.ozdna.com/v1/orgs/org_demo \
  -H "Authorization: Bearer $OZDNA_API_KEY"

Workspace'ler

curl -X POST https://api.ozdna.com/v1/orgs/org_demo/workspaces \
  -H "Authorization: Bearer $OZDNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "slug": "prod"}'

Projeler

curl -X POST https://api.ozdna.com/v1/workspaces/ws_demo/projects \
  -H "Authorization: Bearer $OZDNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "TezMakale Entegrasyonu"}'

API anahtarları

curl -X POST https://api.ozdna.com/v1/projects/proj_demo/keys \
  -H "Authorization: Bearer $OZDNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI deploy", "environment": "test"}'

Yanıt tam key alanını bir kez içerir. Güvenli saklayın — sonraki listeleme çağrıları yalnızca key_prefix gösterir.

Rate limit

Rate limit'ler gateway katmanında API anahtarı başına uygulanır. Limit aşımında 429 Too Many Requests ve Retry-After header'ı döner.

429 yanıtlarında exponential backoff uygulayın. Proaktif throttle için X-RateLimit-Remaining ve X-RateLimit-Reset header'larını kullanın.

Hata kodları

Tüm hatalar error, message ve request_id alanları içeren JSON döner.

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit aşıldı. 30 saniye sonra yeniden deneyin.",
  "request_id": "req_abc123"
}

Dikey modlar

Webhook'lar

webhook_url ile asenkron isteklerde işlem tamamlandığında POST callback gönderilir. Payload, endpoint yanıtı ile aynı yapıdadır; ek olarak job_id ve event alanları bulunur.

İmza doğrulama: X-OzDNA-Signature header'ı (HMAC-SHA256).

OpenAPI spec

Tam OpenAPI 3.1 tanımı beta erişimi ile birlikte yayınlanır:

https://api.ozdna.com/openapi.json
https://api.ozdna.com/openapi.yaml