YZ Görsel Algılama API'si

1. On-imzali Yükleme URL'si Edinin

API'den on-imzali bir URL talep ederek başlayın. Bu URL, görsel dosyanızı depolama sunucusuna güvenli bir şekilde yüklemenizi sağlar.

GET https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg

Örnek İstek

curl -X GET 'https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg' \
--header 'apikey: YOUR API KEY GOES HERE'

Örnek Yanıt

{
  "status": "success",
  "presigned_url": "https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...",
  "file_path": "uploads/example.jpg"
}

2. Görseli Yükleyin

Görselinizi bir PUT isteği ile yüklemek için sağlanan 'presigned_url'i kullanın. Görsel formatınıza göre doğru içerik türünü ayarladığınızdan emin olun.

Örnek İstek

curl -X PUT 'https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...' \
  --header 'Content-Type: image/<FILE_FORMAT - jpeg, jpg, png, webp, heic, heif, avif, bmp, tiff, tif>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg' # Attachment

Yükleme süreci boyunca dosya formatının tutarlı kaldığından emin olun. Başarılı bir yükleme 200 durum kodu döndürecektir.

3. Görseli YZ Algılama İçin Gönderin

Yükledikten sonra, önceki adımdan alınan 'file_path'e referans vererek görseli YZ algılama için gönderin.

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

Örnek İstek

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>",
  "generate_preview": false,
  "generate_analysis_details": true
}'

'FILE_PATH', ilk adım olan 'On-imzali Yükleme URL'si Edinin' yanıtından alınan yolu ifade eder.

Örnek Yanıt

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending"
}

Yanıt, algılama durumunu izlemek için benzersiz bir görsel kimliği içerir.

1. İlk Sonuç Yerleşir (Analiz Hala Beklemede)

generate_analysis_details: true ile gönderip 'done' durumunda ilk sorgulamayı yaptığınızda, temel algılama sonuçları (result, final_result, confidence) hazırdır. Ancak analysis_results_status 'pending' olabilir — bu, derin YZ analizinin hala arka planda işlendiği anlamına gelir.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

2. Analiz Sonuçları İçin Sorgulamaya Devam Edin

Aynı görsel kimliği ile /query üç noktasını çağırmaya devam edin. Her yanıttaki analysis_results_status alanını kontrol edin. 'pending'den 'done'a değiştiğinde analysis_results nesnesi doldurulacaktır.

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}'

3. Analiz Tamamlandı — Tam Yanıt

analysis_results_status 'done' olduğunda, analysis_results nesnesi uyum düzeyi, güven, temel göstergeler, detaylı mühakeme, görsel desenler ve öneriler içeren tam derin YZ analizini içerir.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "done",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 92,
            "keyIndicators": [
                "Unnaturally smooth skin texture",
                "Consistent lighting anomalies"
            ],
            "detailedReasoning": "The image shows clear signs of AI generation with unnaturally smooth textures and consistent lighting patterns not typical of real photography.",
            "visualPatterns": [
                "Uniform noise pattern typical of diffusion models"
            ],
            "recommendations": [
                "Cross-reference with original source if available",
                "Check for metadata inconsistencies",
                "Compare with known AI generation patterns"
            ]
        }
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

Analiz Mevcut Olmadığında

analysis_results_status 'skipped', null veya yoksa, bu görsel için derin analiz üretilmeyecektir. Bu, /detect isteğinde 'generate_analysis_details' 'true' olarak ayarlanmadığında veya belirli görsel türleri ve algılama senaryoları için olur. İlk algılama sonuçlarını nihai olarak kabul etmelisiniz.

{
    "status": "done",
    "result": 12.5,
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

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

Neden: Gecersiz veya süresi dolmus API anahtari

Çö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: Görsel 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 yüklemeden önce görsel boyutunu optimize edin

"Desteklenmeyen dosya formati" (400)

Neden: Desteklenmeyen veya geçersiz görsel formatı gönderildi

Çözüm:

1. Görsel formatının desteklendiğinden emin olun (JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF)
2. Dosyanın bozuk olmadığından emin olun
3. Yüklerken Content-Type başlığını kontrol edin

"Dosya çok büyük" (400)

Neden: Dosya boyutu 10MB sınırını aşıyor

Çözüm:

1. Görseli 10MB'in altina yeniden boyutlandirin veya sıkıştırın
2. Yüklemeden önce dosya boyutunu kontrol edin
3. Mümkün olduğunda WebP gibi daha verimli formatlar kullanın

"Istek zaman aşımı" (WebSocket)

Neden: Görsel işleme çok uzun surdu

Çözüm:

1. Daha küçük veya daha az karmaşık bir görselle 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. Görselin minimum gereksinimleri karşılayıp karşılamadığını kontrol edin (1KB - 10MB)
2. Görselin desteklenen bir formatta olduğundan emin olun
3. Algılama için göndermeden önce yüklemenin başarıyla tamamlandığını doğrulayın
4. Sorun devam ederse destekle iletişime geçin

"Görsel yükleme başarısız oldu" (403/400)

Neden: Gecersiz veya süresi dolmus on-imzali URL veya depolama sunucusu sorunlari

Çözüm:

1. On-imzali URL'yi aldiktan hemen sonra kullandığınızdan emin olun (süresi dolabilir)
2. Content-Type basliginin görsel formati için doğru olduğunu doğrulayın
3. Yüklemeden önce dosya adından boşlukları kaldırın
4. Mevcut URL'nin süresi dolduysa yeni bir on-imzali URL oluşturmayı deneyin

"Gecersiz on-imzali URL" (400)

Neden: Boşluklu dosya adı veya süresi dolmus/bozuk on-imzali URL

Çözüm:

1. On-imzali URL talep etmeden önce dosya adından tüm boşlukları kaldırın
2. Dosya adinda yalnızca alfanumerik karakterler, tireler ve alt çizgiler kullanın
3. Gerekirse yeni bir on-imzali URL oluştürün