API Referansı

ozDNA REST API, OzDNA GPT motorunu B2B entegrasyonlara açar. JSON istek/yanıt, Bearer token kimlik doğrulama ve OpenAPI 3.1 uyumlu sözleşme.

Giriş

API iki çekirdek yetenek sunar: AI metin dedeksiyonu (/v1/detect) ve humanizasyon (/v1/humanize). Her iki endpoint segment düzeyinde çıktı, dikey mod kalibrasyonu ve çok dilli destek sağlar.

tezmakale.com üzerinde aynı motor production'da çalışmaktadır; B2B API katmanı backend olgunlaştıkça açılmaktadır.

Kimlik doğrulama

Tüm isteklerde 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.

Base URL

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

POST /v1/detect

Metin içinde AI üretimi olasılığını segment düzeyinde analiz eder.

Alan	Tip	Açıklama
text zorunlu	string	Analiz edilecek metin (max 50.000 karakter)
mode	string	academic · legal · financial · general
language	string	ISO 639-1 — örn. tr, en
webhook_url	string	Asenkron işlem için callback URL (Growth+)

Örnek istek

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

Örnek yanıt

{
  "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/humanize

AI üretimi metni doğal prose'ye dönüştürür; anlam ve register korunur.

Alan	Tip	Açıklama
text zorunlu	string	Humanize edilecek metin
mode	string	Dikey mod — detect ile aynı değerler
language	string	ISO 639-1 dil kodu
intensity	string	light · medium · strong
preserve_terms	string[]	Değiştirilmemesi gereken terimler (hukuk/finans)

Örnek yanıt

{
  "text": "Bu araştırmada izlenen yöntem...",
  "ai_probability_before": 0.91,
  "ai_probability_after": 0.18,
  "processing_ms": 6200,
  "intensity": "medium"
}

Not: Humanize gecikmesi metin uzunluğuna bağlıdır. Beta sürecinde ortalama süre verileri toplanmaktadır.

POST /v1/batch

Toplu detect veya humanize işlemleri. Growth ve Enterprise planlarında kullanılabilir. İşlem asenkron tamamlanır; sonuç webhook_url ile iletilir veya GET /v1/batch/{id} ile sorgulanır.

Dikey modlar

Mod	Kullanım	Hedef segment
academic	Akademik metin, tez, makale	Üniversite, EdTech, OzDNA Academic
legal	Sözleşme, dilekçe, mevzuat metni	Hukuk firmaları, OzDNA Comply
financial	Rapor, uyum metni, düzenleyici içerik	Fintech, EMI/PSP, RegTech
general	Genel amaçlı metin	Varsayılan

Webhook'lar

Asenkron isteklerde webhook_url belirtildiğinde işlem tamamlandığında POST callback gönderilir. Payload, ilgili 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 ile doğrulanır.

Hata kodları

400Geçersiz istek — eksik text veya desteklenmeyen mode

401Geçersiz veya eksik API anahtarı

402Kota aşıldı — plan limitine ulaşıldı

429Rate limit — Retry-After header'ına bakın

503Geçici servis kesintisi — exponential backoff ile yeniden deneyin

OpenAPI spec

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

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

Production API erişimi şu an davet usulü. Dokümantasyon güncellendikçe bu sayfa genişletilecektir.

Bekleme Listesine Katıl