Tipik bir belge için çağrı gecikmesi nedir?

500 kelimelik bir metnin indekslenmiş korpus üzerinde kontrolü için p50 yaklaşık 600 ms, p95 ise yaklaşık 1,8 sn. Layer W (canlı web doğrulaması) etkinleştirildiğinde yaklaşık 2 sn eklenir — bu işlem Google ve Brave üzerinden çift yönlü gerçekleşir. Uzun belgelerde (8 sn'den fazla işlem süresi beklenen) kontrol hemen bir check_id ile başlatılır ve sonuç webhook ile iletilir.

Fiyatlandırma API'ye göre nasıl ölçülür?

/v1/checks isteği başına bir ücretlendirme yapılır, belge boyutu plan sınırına kadar (1.500 kelime Pro, 50.000 Premium, kurumsal için özel). 24 saat içinde aynı Idempotency-Key + gövde ile yapılan tekrarlar çift sayılmaz. /v1/checks/{id} okuma ve SDK ek çağrıları ücretsiz.

API'yi kendi sunucumda çalıştırabilir miyim?

Evet — github.com/NoplagLabs/noplag-engine, engine.noplag.app üzerinde çalışan Apache 2.0 referans uygulamasının aynısıdır. docker compose up komutu ile yerel /v1/checks uç noktasını çalıştırabilirsiniz. Bulut katmanında yönetilen korpus ve Google/Brave API anahtarları eklenir; tam self-host için kendi anahtarlarınızı kullanmanız gerekir.

Güvenilir bir hız limiti tekrar başlığı var mı?

429 durumunda Retry-After saniye olarak döner. Tüm yanıtlarda X-RateLimit-* başlıkları da döner — 429 beklemeden X-RateLimit-Remaining ile ön-taramalı yanıt verebilirsiniz. Her ikisi de doğru ve dağıtımlarda kararlı.

SDK sürümleme sıklığı nedir?

Python ve Node SDK'lar openapi.yaml'den her motor etiketinde otomatik üretilir. Ana motor sürümleri (v0.x → v0.y) SDK'da da aynı gün çıkar. Yama düzeltmeleri aynı hafta yayımlanır. İki SDK da semver'e uyar; ana API yüzeyi yalnızca /v1 → /v2'de değişir.

Corpus ay içinde değişirse ne olur?

Her kontrol X-Engine-Commit ve corpus anlık görüntü zaman damgası ile işaretlenir. Eski bir kontrolü yeni corpus ile çalıştırmak bir sorgu parametresi ile yapılır (?corpus_snapshot=…). Orijinal rapor, orijinal snapshot ile korunur — geçmiş bir benzerlik puanı sessizce değiştirilmez.

Aylık kotamı harcamadan nasıl test ederim?

Test anahtarları (nplg_test_…) bir kum havuzuna gönderir: tam API yüzeyi, asla kalıcı veri tutmaz, aylık kota veya hız limitine dahil edilmez. Webhooklar da kum havuzundan çalışır — uçtan uca entegrasyon testi ücreti yok.

Toplu kontrollerde en doğru yaklaşım nedir?

Hız limitiniz kadar paralelde gönderin — toplu uç nokta yok (tasarım gereği: 500 belgede 312'ncide hata almak 500 bağımsız çağrıdan kötü). Yüksek hacimli akışlar için API'yi webhooklarla birlikte kullanın: gönderin, check_id anında dönsün, sonraki 200 başvuruyu girin, sonuçlar geldikçe sırayla işleyin.

Bir kontrolü yalnızca kendi klasörlerime sınırlayabilir miyim?

Evet — istek gövdesinde corpora: [] ile folder_id geldiğinde yalnızca kullanıcıya özel klasörlere karşı eşleşir. corpora: ["academic"] ile “sadece akademik + kendi klasörlerim” seçeneği de mümkün. Çağrı bazında kapsam; ek bir faturalandırma seviyesi gerekmez.

AB yerleşimi veya kurum içi yapılandırma istiyorsam ne değişir?

Kurumsal seviye, AB veri yerleşimli özel uç nokta (api.eu.noplag.com) sağlar, aynı OpenAPI yüzeyi, kişisel veri EEA içinde kalır. Ya da referans uygulamayı tamamen kendi VPC'nize kurun — aynı motor, aynı /v1 kontratı, ağınızdan dışarıya veri çıkmaz. (Açık çekirdek modeline geçtik; SOC 2 gibi resmi belgeler yol haritasında, henüz hazır değil — bu arada sunabildiğimiz şey denetlenebilir bir motor.)

RESTOpenAPI 3.0 spesifikasyonu · Python + Node SDK'lar · v0.4.2

İntihal kontrolü API: REST ve SDK seçenekleri

İntihal + yapay zeka tespiti için doğrudan kullanılabilir REST uç noktası. OpenAPI 3.0 spesifikasyonu, Python ve Node SDK'ları, Apache 2.0 referans uygulaması. İlk curl çağrınızdan webhook tabanlı hacime — noplag.com'dakiyle aynı motor.

REST · OpenAPI 3.0Python + Node SDK'larApache 2.0 referans uygulama

İLK ÇAĞRI

Bir curl ile sıfırdan benzerlik puanına.

POST ile metni gönderin, puanlanmış aralıkları alın. SDK gerekmez, derleme adımı yok, özel bir veri formatı yok.

İSTEK · bashKopyala

$ curl https://engine.noplag.app/v1/checks \    -H "Authorization: Bearer $NOPLAG_KEY" \    -H "Content-Type: application/json" \    -H "Idempotency-Key: $(uuidgen)" \    -d '{        "text": "The rain in Spain falls...",        "corpora": ["web", "academic"],        "ai_detection": true,        "webhook_url": "https://you.example/hook"    }'

YANIT · 200 OK · application/jsonKopyala

{  "check_id": "chk_01HX9R2Y4...",  "status": "complete",  "similarity_pct": 23.4,  "ai_score": 0.08,  "engine_commit": "v0.4.2",  "sources": [    { "url": "https://en.wikipedia...",      "matched_chars": 142,      "similarity_pct": 100.0 }  ]}

UÇ NOKTALAR

Dört uç nokta. Tek sözleşme. URL'de sürümlü.

Aynı OpenAPI 3.0 spesifikasyonu hem açık kaynak kodlu depoda hem de engine.noplag.app üzerinde bulunur. SDK’lar her etiketli sürümde bu spesifikasyondan yeniden oluşturulur.

POST/v1/checksBir denetim gönder8 saniyeye kadar eş zamanlı; üzeri için webhook ile çağrılır. Idempotency-Key gerekli.

GET/v1/checks/{id}Bir denetimi getirSon rapor durumunu döndürür. Accept: text/event-stream ile aralıklar anlık alınabilir.

GET/v1/sources/{id}Bir kaynağı inceleEşleşen bir kaynağı ID ile çözer — tam URL, anlık görüntü tarihi, önbellekten mi canlı mı alınmış.

POST/v1/foldersKlasörleri yönetDenetim oluştur / listele / taşı. Kapsamı klasör bazında kullanıcıya özel dökümanlarla sınırlar.

POST/v1/webhooksBir webhook kaydetHMAC imzası ile iletim; 24 saatte üstel tekrar; gösterge panelinden iletimi yeniden oynat.

Tüm referans api./docs adresinde.openapi.yaml

KİMLİK DOĞRULAMA + HIZ LİMİTLERİ

Bearer tokenlar. Idempotency anahtarları. Net hız limit başlıkları.

Karmaşık bir şey yok. Standart HTTP kavramları — onları takip ediyoruz, böylece mevcut yeniden deneme ara yazılımınız çalışır.

KİMLİK DOĞRULAMA

Bearer tokenlar. Tek başlık, imza dansı yok.

Bir anahtar oluşturunKontrol paneli → Ayarlar → API. Anahtarlar kapsamlıdır (okuma / yazma / yönetici) ve iki tıklama ile döndürülebilir.

Her çağrıda iletinAuthorization: Bearer nplg_live_…. Test anahtarları (nplg_test_) asla kalıcı olmayan bir kum havuzunu kullanır.

POST'larda Idempotency-Key ekleyinHerhangi bir UUID kullanılabilir. Aynı anahtar + içerik 24 saat boyunca önbelleğe alınmış yanıtı döndürür, bu sayede tekrarlar çift ücretlendirme veya tekrar kontrol oluşturmaz.

Authorization: Bearer nplg_live_a82f...Idempotency-Key: 0e8f9c44-...

HIZ LİMİTLERİ

Anahtar başı, dakika başı. Başlıklar tam olarak neredesiniz gösterir.

SEVİYEİST/DAKAYLIKPATLAMA

Ücretsiz10100 / ay20

Pro601.000 / ay120

Premium30010.000 / ay600

KurumsalÖzelAnlaşmaya bağlıÖzel

X-RateLimit-Limit: 60X-RateLimit-Remaining: 41X-RateLimit-Reset: 1747920480Retry-After: 19  (only on 429)

SDK'LAR

İki SDK. Aynı OpenAPI 3.0 spesifikasyonundan türetilir.

Python + Node her etiketli motor sürümünde yayınlanır. Diğer diller (Go, Ruby, Java) openapi.yaml'den üretilir — topluluk PR'ları kabul edilir.

PYTHONpip install noplag

from noplag import Noplag client = Noplag(api_key="nplg_live_…") report = client.checks.create(    text="...",    corpora=["web", "academic"],    ai_detection=True,) print(report.similarity_pct)

NODEnpm i @noplag/sdk

import Noplag from "@noplag/sdk"; const client = new Noplag({    apiKey: process.env.NOPLAG_KEY,}); const report = await client.checks.create({    text: "...",    corpora: ["web", "academic"],    aiDetection: true,});

<200msp95 gecikme

99,95%uptime SLA

3bölgeler (US/EU/AP)

OAPI 3spesifikasyon formatı

Apache 2.0referans uygulama

WEBHOOKLAR

Uzun süren denetimler size geri çağrı yapar. Tekrarlar mantıklı, karmaşık değil.

Dört olay türü. JSON içerik. Başlıkta HMAC-SHA256 imzası.

check.completedRapor hazır · tüm raporun JSON'u gömülü

check.failedKalıcı hata · hata kodu + tekrar önerisi içerir

check.progressAra ilerleme · şu ana kadar çözülen kaynaklar

folder.sharedKlasör erişimi bir ekip üyesine veya dış denetçiye verildi

24 saat boyunca üstel tekrar. Gösterge panelinden tekrar oynatabilirsiniz.

Tekrar eğrisi5s, 30s, 2dk, 10dk, 1sa, 6sa, 24sa — sonra dead-letter

Zaman aşımıBağlantı 10s, deneme başına toplam 30s

Başarı kriteriHTTP 2xx yanıtı pencerede; yönlendirmeleri takip ediyoruz

Tekrar oynatma UI'siGösterge panelinden herhangi bir iletimi seçin ve farklı bir URL'ye tekrar gönderin

İmzayı kontrol edin. Sonucu hesaplanamayanı reddedin.

Her iletimde X-Noplag-Signature: t=<unix>,v1=<hex> başlığı var. Zaman damgası + gövde ile webhook secret'ınızı kullanarak HMAC-SHA256 hesaplayın ve sabit zamanlı karşılaştırma yapın.

h = hmac.new(secret,    f"{t}.{body}".encode(),    hashlib.sha256).hexdigest()assert hmac.compare_digest(h, v1)

GELİŞTİRİCİ İLKELERİ

HTTP'yi takip ediyoruz. Bütün API tasarım belgesi bu.

POST'larda idempotent. Sürümü URL'de belirtiyoruz. Hatalar ne yapacağınızı açıkça yazar. Hız limitini başlıklarda tam olarak gösteririz. Sayfalama cursor ile, offset değil. UTC ISO 8601 zaman damgaları. Özel HATEOAS dili yok, hatada 200 OK döndürmüyoruz, sunucu-sunucu çağrısında OAuth zorunluluğu yapmıyoruz. API tasarımı için belgeler: RFC 9110 ve OpenAPI 3.0 — ayrıca bir “Noplag Yöntemi” öğrenmenizi istemiyoruz.

Tasarım notlarını okuyun

TASARIM KISITLARI

IDEMPAynı Idempotency-Key + gövde ile 24 saatte tekrar istekde önbellekli yanıt değişmez. Ağ hatasında aynı anahtarla yeniden deneyin — çift ücret veya tekrar denetim oluşmaz.

VERBüyük sürüm URL'de (/v1, /v2). Geriye dönük uyumsuz değişiklikte yeni sürüm yolu — eski sürüm duyurudan sonra 12 ay desteklenir.

ERRTüm 4xx/5xx hatalarında RFC 9457 problem-details JSON'u. type, title, detail, instance ve noplag.retry_strategy ipucu.

PAGHer liste uç noktasında cursor tabanlı. ?limit=100&cursor=… sorgusu gövdede next_cursor döndürür. Sayfa 47'de yeni satırlar geldiğinde offset ile kayma yaşanmaz.

OBSYanıtta X-Engine-Commit, X-Request-Id ve aşama başına Server-Timing eklenir. Herhangi bir denetimi ID ile tekrar oynatabilirsiniz; rapordan o denetimi oluşturan motor sürümüne erişebilirsiniz.

OPENApache 2.0 lisanslı referans uygulaması github.com/NoplagLabs/noplag-engine adresinde. Verileriniz ağınızdan çıkamıyorsa çağrıyı kendi altyapınızda barındırabilirsiniz — aynı API arayüzü.

SSS

Entegrasyon mühendislerimizin sorduğu gerçek sorular.

Tipik bir belge için çağrı gecikmesi nedir?: 500 kelimelik bir metnin indekslenmiş korpus üzerinde kontrolü için p50 yaklaşık 600 ms, p95 ise yaklaşık 1,8 sn. Layer W (canlı web doğrulaması) etkinleştirildiğinde yaklaşık 2 sn eklenir — bu işlem Google ve Brave üzerinden çift yönlü gerçekleşir. Uzun belgelerde (8 sn'den fazla işlem süresi beklenen) kontrol hemen bir check_id ile başlatılır ve sonuç webhook ile iletilir.
Fiyatlandırma API'ye göre nasıl ölçülür?: /v1/checks isteği başına bir ücretlendirme yapılır, belge boyutu plan sınırına kadar (1.500 kelime Pro, 50.000 Premium, kurumsal için özel). 24 saat içinde aynı Idempotency-Key + gövde ile yapılan tekrarlar çift sayılmaz. /v1/checks/{id} okuma ve SDK ek çağrıları ücretsiz.
API'yi kendi sunucumda çalıştırabilir miyim?: Evet — github.com/NoplagLabs/noplag-engine, engine.noplag.app üzerinde çalışan Apache 2.0 referans uygulamasının aynısıdır. docker compose up komutu ile yerel /v1/checks uç noktasını çalıştırabilirsiniz. Bulut katmanında yönetilen korpus ve Google/Brave API anahtarları eklenir; tam self-host için kendi anahtarlarınızı kullanmanız gerekir.
Güvenilir bir hız limiti tekrar başlığı var mı?: 429 durumunda Retry-After saniye olarak döner. Tüm yanıtlarda X-RateLimit-* başlıkları da döner — 429 beklemeden X-RateLimit-Remaining ile ön-taramalı yanıt verebilirsiniz. Her ikisi de doğru ve dağıtımlarda kararlı.
SDK sürümleme sıklığı nedir?: Python ve Node SDK'lar openapi.yaml'den her motor etiketinde otomatik üretilir. Ana motor sürümleri (v0.x → v0.y) SDK'da da aynı gün çıkar. Yama düzeltmeleri aynı hafta yayımlanır. İki SDK da semver'e uyar; ana API yüzeyi yalnızca /v1 → /v2'de değişir.
Corpus ay içinde değişirse ne olur?: Her kontrol X-Engine-Commit ve corpus anlık görüntü zaman damgası ile işaretlenir. Eski bir kontrolü yeni corpus ile çalıştırmak bir sorgu parametresi ile yapılır (?corpus_snapshot=…). Orijinal rapor, orijinal snapshot ile korunur — geçmiş bir benzerlik puanı sessizce değiştirilmez.
Aylık kotamı harcamadan nasıl test ederim?: Test anahtarları (nplg_test_…) bir kum havuzuna gönderir: tam API yüzeyi, asla kalıcı veri tutmaz, aylık kota veya hız limitine dahil edilmez. Webhooklar da kum havuzundan çalışır — uçtan uca entegrasyon testi ücreti yok.
Toplu kontrollerde en doğru yaklaşım nedir?: Hız limitiniz kadar paralelde gönderin — toplu uç nokta yok (tasarım gereği: 500 belgede 312'ncide hata almak 500 bağımsız çağrıdan kötü). Yüksek hacimli akışlar için API'yi webhooklarla birlikte kullanın: gönderin, check_id anında dönsün, sonraki 200 başvuruyu girin, sonuçlar geldikçe sırayla işleyin.
Bir kontrolü yalnızca kendi klasörlerime sınırlayabilir miyim?: Evet — istek gövdesinde corpora: [] ile folder_id geldiğinde yalnızca kullanıcıya özel klasörlere karşı eşleşir. corpora: ["academic"] ile “sadece akademik + kendi klasörlerim” seçeneği de mümkün. Çağrı bazında kapsam; ek bir faturalandırma seviyesi gerekmez.
AB yerleşimi veya kurum içi yapılandırma istiyorsam ne değişir?: Kurumsal seviye, AB veri yerleşimli özel uç nokta (api.eu.noplag.com) sağlar, aynı OpenAPI yüzeyi, kişisel veri EEA içinde kalır. Ya da referans uygulamayı tamamen kendi VPC'nize kurun — aynı motor, aynı /v1 kontratı, ağınızdan dışarıya veri çıkmaz. (Açık çekirdek modeline geçtik; SOC 2 gibi resmi belgeler yol haritasında, henüz hazır değil — bu arada sunabildiğimiz şey denetlenebilir bir motor.)

Bir API anahtarı alın. İlk çağrınızı yapın.

Ücretsiz deneme 100 API çağrısı içerir. Pro paketi 1.000 çağrı için $23/ay. Çağrılarınız ağınızda kalacaksa Apache 2.0 referans uygulama.

API anahtarı alın OpenAPI spesifikasyonunu okuyun