API Dokümantasyonu
ISO 27001SOC 2 CertifiedGDPR Compliant

YZ Metin Algılama API'si

TruthScan'in YZ algılama API'sini uygulamalarınıza entegre etmek için eksiksiz dokümantasyon.

Kod yazmadan denemek için FastAPI uç noktamızı ziyaret edin: https://detect-text.truthscan.com/docs

Kimlik Doğrulama

TruthScan, API'ye erişim için API anahtarları kullanır. API anahtarınızı geliştirici portalımızın üst kısmında.

TruthScan, API anahtarının sunucuya yapılan tüm API isteklerinde aşağıdaki gibi bir istek gövdesinde yer almasını bekler:

{
  "key": "YOUR API KEY GOES HERE"
}

YOUR API KEY GOES HERE yazan yeri kişisel API anahtarınızla değiştirmelisiniz.

Web socket senaryoları için Organizasyon Kimliğinizi URL'nin bir parçası olarak göndermeniz gerekecektir. Organizasyon Kimliğinizi geliştirici portalımızın üst kısmında.

TruthScan, Organizasyon Kimliğinizin tüm web socket isteklerinin URL'sine dahil edilmesini bekler. Dokümantasyon aşağıdaki gibi görünecektir:

wss://detect-text.truthscan.com/ws/$ORG_ID

$ORG_ID yazan yeri kişisel Organizasyon Kimliğinizle değiştirmelisiniz.

YZ Algılayıcı

Algılama

Bu üç nokta, metin göndererek YZ algılaması yapmanızı sağlar. En iyi doğruluk için en az 200 kelime önerilir.

POST https://detect-text.truthscan.com/detect

Eşik

Bu üç nokta 1-100 aralığında bir "result" skoru döndürür. En iyi doğruluk için, 50'nin altındaki herhangi bir skor kesinlikle insan olarak kabul edilir. 50-60 muhtemel YZ'dir. 60 üstü kesin YZ'dir. Bu, %99+ doğrulukla en hassas sonuçtur.

Writer ve Copyleaks gibi diğer algılayıcılar için skorlar yaklaşıktır ve ana "result" skoru kadar doğru değildir.

Satır sonları

Veriyi JSON olarak gönderiyorsanız, satır sonları dize içinde \n olarak kodlanmalıdır.

Örnek İstek

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "On Citizen science\nCitizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "retry_count": 0
}'

Burada istek girdisi 30.000 kelimeden az olmalıdır.

Örnek Yanıt

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "input": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
    "model": "xlm_ud_detector",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

Yanıt, sunucu tarafından atanmış belge kimliğini içerir. Bu noktada belge işleme için sıraya alınmıştır. YZ Algılama isteğinin durumunu sorgulamak için /query API üç noktasını kullanabilirsiniz. Bir YZ Algılama kontrolünü tamamlamak için ortalama süre 2-4 saniye arasındadır. Kelime sayısına bağlı olarak daha uzun sürebilir.

Sorgulama

Bu üç nokta, /detect isteği tarafından döndürülen bir belge kimliğini kabul eder. Ve belge gönderiminin durumunu ile çeşitli üçüncü taraf YZ algılayıcıları tarafından işlenen YZ Algılama işleminin sonuçunu döndürür.

POST https://detect-text.truthscan.com/query

Örnek İstek

curl -X 'POST' \
  'https://detect-text.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "DOCUMENT-ID-GOES-HERE"
}'

Örnek Yanıt

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "result": 12.0,
    "result_details": {
        "scoreGptZero": 50.0,
        "scoreOpenAI": 0.0,
        "scoreWriter": 0.0,
        "scoreCrossPlag": 0.0,
        "scoreCopyLeaks": 50.0,
        "scoreSapling": 0.0,
        "scoreContentAtScale": 0.0,
        "scoreZeroGPT": 50.0,
        "human": 88.0
    },
    "status": "done",
    "retry_count": 0
}

"result": 12.0, girdinin insanlığın bir göstergesidir. Bu, %50 eşiğinin altında olduğu için metnin kesinlikle insan tarafından yazıldığını gösterir. Benzer şekilde result_details altındaki değerler girdinin insanlığını gösterir.

Kullanıcı Kredilerini Kontrol Et

Bu üç nokta, başlık aracılığıyla kullanıcının apikey'ini kabul eder. Ve kullanıcının kredi ayrıntılarını döndürür.

GET https://detect-text.truthscan.com/check-user-credits

Örnek İstek

curl -X 'GET' \
  'https://detect-text.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

Örnek Yanıt

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

Cümle Düzeyinde YZ Algılama

Cümle düzeyinde YZ Algılayıcı, WebSocket tabanlı bir protokol üzerinde çalışır.

Metniniz için cümle düzeyinde sonuçlar almak için gereken adımlar:

  • WebSocket'e bağlanın
  • WebSocket'ten alınan tüm olayları dinleyin
  • Bir document_watch isteği gönderin
  • Bir document_id olayı alın
  • document_id yanıtından üretilen kimlik ile YZ Algılama için bir belge gönderin
  • document_chunk olaylarını almaya başlayın. document_chunk olayları her cümleyi cümle düzeyindeki sonuçla birlikte döndürür
  • Belge işleme tamamlandığında bir document_done olayı alacaksınız

WebSocket'e Bağlanın

Bu üç nokta WebSocket bağlantısı kurmanızı sağlar

wss://detect-text.truthscan.com/ws/$ORG_ID

Örnek kod

ws = new WebSocket("wss://detect-text.truthscan.com/ws/1722238709737x2194626580942121212");

WebSocket'ten alınan tüm olayları dinleyin

WebSocket bağlantısı kurulduktan sonra, WebSocket bağlantısı üzerinden gönderilen olayları dinleyin.

Örnek kod

ws.addEventListener("message", (event) => {
  console.log("Message from server ", event.data);
});

Bir document_watch isteği gönderin

WebSocket üzerinde bir document_watch isteği göndererek belge gönderme ilginizi bildirin

Örnek kod

ws.send(JSON.stringify({
    "event_type": "document_watch",
    "api_key": "$API_KEY",
}))

Bir document_id olayı alın

document_watch olayı gönderdikten sonra sunucu bir document_id olayı döndürür.

Örnek yanıt

{
  "event_type": "document_id",
  "success": true,
  "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

Bir YZ Algılama İsteği Gönderin

document_id yanıtından üretilen kimliği alın ve YZ Algılama için bir belge gönderin

POST https://detect-text.truthscan.com/detect

Örnek İstek

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}'

Cümle düzeyinde sonuçları alın

document_chunk olaylarını almaya başlayın. document_chunk olayları her cümleyi cümle düzeyindeki sonuçla birlikte döndürür

Örnek yanıtlar

{
    "event_type": "document_chunk",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector",
    "chunk": "Citizen science involves the public in scientific research.",
    "result": 0.714
}

Belge işleme tamamlandığında bir document_done olayı alacaksınız.

Örnek yanıtlar

{
    "event_type": "document_done",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector"
}

İstisnai durumların yönetimi

YZ algılama sırasında sunucu bir hatayla karşılaşırsa, websocket istemcisine bir document_error olayı gönderilir. İstemci uygun şekilde davranmalıdır, örneğin bir kullanıcı arayüzü bir hata mesajı gösterebilir.

Örneğin, chunk olayları arasında 20 saniyeden fazla sürerse sunucu bir REQUEST_TIMEOUT hata kodu gönderir.

{
    "event_type": "document_error",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "error_code": "REQUEST_TIMEOUT",
    "message": "Request timeout. Took 20 seconds."
}

İptaller

Kullanıcı arayüzünün işlemi iptal etmek isteyeceği durumlar olacaktır. Kullanıcı pencereyi kapatmaya karar verir veya olayı açıkça iptal eder

Bu olduğunda bir document_halt olayı göndermelisiniz

Örnek yanıtlar

{
    "event_type": "document_halt",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

Hatalar

Hataların çoğu, API'ye yanlış parametreler gönderilmesinden kaynaklanır. Her API çağrısının parametrelerinin doğru biçimlendirildiğinden emin olmak için iki kez kontrol edin ve sağlanan örnek kodu çalıştırmayı deneyin.

Kullandığımız genel hata kodları REST standardına uygundur:

Hata KoduAnlam
400Hatalı İstek -- İsteğiniz geçersiz.
403Yasak -- API anahtarı geçersiz veya yeterli kredi yok (kelime başına 0.1).
404Bulunamadı -- Belirtilen kaynak mevcut değil.
405Yönteme İzin Verilmiyor -- Geçersiz bir yöntemle kaynağa erişmeye çalıştınız.
406Kabul Edilemez -- JSON olmayan bir format talep ettiniz.
410Kaldırıldı -- Bu üç noktadaki kaynak kaldırıldı.
422Geçersiz İstek Gövdesi -- İstek gövdeniz yanlış biçimlendirilmiş veya geçersiz veya eksik parametreleri var.
429Çok Fazla İstek -- Çok fazla istek gönderiyorsunuz! Yavaşlayın!
500Dahili Sunucu Hatası -- Sunucumuzda bir sorun yaşadık. Daha sonra tekrar deneyin.
503Hizmet Kullanım Dışı -- Bakım için geçici olarak çevrimdışıyız. Lütfen daha sonra tekrar deneyin.

Yaygın Sorunlar ve Çözümler

Kimlik Doğrulama Sorunları

"Kullanıcı doğrulaması başarısız oldu" (403)

Neden: Geçersiz veya süresi dolmuş API anahtarı

Çözüm:

  1. API anahtarınızın doğru olduğundan emin olun
  2. API anahtarınızın hesabınızda aktif olup olmadığını kontrol edin
  3. API anahtarınızı yeniden oluşturmayı deneyin

"Yeterli kredi yok" (403)

Neden: Metin işleme için yetersiz kredi

Çözüm:

  1. Kalan kredilerinizi /check-user-credits ile kontrol edin
  2. Gerekirse ek kredi satın alın
  3. Daha az kredi tüketmek için daha kısa metin girişleri kullanın

Girdi Doğrulama Sorunları

"Girdi metni boş olamaz" (400)

Neden: Boş veya yalnızca boşluk karakteri içeren metin gönderildi

Çözüm:

  1. Metin girdinizin boş olmadığından emin olun
  2. Başlangıç/bitiş boşluklarını kaldırın
  3. Metin kodlamasının doğru olduğundan emin olun

"Girdi e-postasi bos" (400)

Neden: URL işleme için eksik e-posta

Çözüm:

  1. URL gönderirken geçerli bir e-posta adresi sağlayın
  2. E-posta formatının doğru olduğundan emin olun

İşleme Sorunları

"İstek zaman aşımı" (WebSocket)

Neden: Belge işleme çok uzun sürdü (>120 saniye)

Çözüm:

  1. Daha küçük bir metin girdisiyle deneyin
  2. Hizmetin yoğun yük altında olup olmadığını kontrol edin
  3. İsteği yeniden deneyin

Belge Durumu "başarısız"

Neden: Çeşitli nedenlerle işleme başarısız oldu

Çözüm:

  1. Girdi metninin minimum gereksinimleri karşılayıp karşılamadığını kontrol edin
  2. Metnin desteklenen bir formatta olduğundan emin olun
  3. Farkli bir modelle deneyin
  4. Sorun devam ederse destekle iletişime geçin

WebSocket Bağlantı Sorunları

Bağlantı Kesintileri

Neden: Ağ sorunları veya sunucu bağlantı kesintileri

Çözüm:

  1. Ağ bağlantınızı kontrol edin
  2. Yeniden bağlantı mantığı uygulayın
  3. WebSocket URL'sinin doğru olduğundan emin olun

"Kullanıcı bulunamadı" (WebSocket)

Neden: WebSocket bağlantısında geçersiz Organizasyon Kimliği

Çözüm:

  1. Organizasyon Kimliğinizin doğru olduğundan emin olun
  2. Kullanıcı hesabının aktif olduğundan emin olun
  3. Gerekirse yeniden kimlik doğrulaması yapın

Yardıma mı İhtiyacınız Var?

API'mizi kullanma veya teknik destek hakkında daha fazla bilgi için lütfen bizimle iletişime geçin.

API Sıkça Sorulan Sorular

YZ algılama API'miz hakkında en sık sorulan soruların cevaplarını bulun.