AI Image Detection API

1. Pre-signed Upload URL alın

Önce API'den pre-signed URL isteyin. Bu URL, görüntü dosyanızı depolama sunucusuna güvenli şekilde yüklemenizi sağlar.

PDF dosyalarında yalnızca ilk görüntü detection için kullanılır (tek dosya akışı).

ZIP'i bulk upload ile gönderecekseniz bu endpoint'te .zip dosya adı kullanın.

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

Örnek istek

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://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...",
  "file_path": "uploads/example.jpg",
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

document_id bu yükleme isteği için yeni üretilen bir UUID'dir (korelasyon/loglama). /detect veya /bulk-upload için kullanacağınız id, bu endpoint'lere gönderdiğinizde atanır; /detect'e isteğe bağlı id vermezseniz sunucu atar.

2. Görüntüyü yükleyin

Verilen presigned_url ile görüntünüzü PUT isteğiyle yükleyin. Görüntü formatınıza uygun Content-Type'ı doğru ayarlayın.

Örnek istek

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...' \
  --header 'Content-Type: image/jpeg' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg'

Ek yükleme örnekleri (PNG, PDF, SVG)

curl -X PUT '<PRESIGNED_URL_FOR_example.png>' \
  --header 'Content-Type: image/png' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.png'

curl -X PUT '<PRESIGNED_URL_FOR_example.pdf>' \
  --header 'Content-Type: application/pdf' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.pdf'

curl -X PUT '<PRESIGNED_URL_FOR_example.svg>' \
  --header 'Content-Type: image/svg+xml' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.svg'

Yükleme boyunca dosya formatının tutarlı kalmasını sağlayın. Başarılı yükleme HTTP 200 döner.

3. AI detection için görüntüyü gönderin

Yüklemeden sonra, önceki adımdaki file_path ile görüntüyü AI detection için gönderin. PDF yüklemelerinde yalnızca ilk görüntü analiz/detection edilir.

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

Örnek istek

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": true
}'

FILE_PATH, pre-signed URL adımında dönen yoldur (ör. uploads/...). Örnekte gösterildiği gibi storage host'unuzla tam URL'yi oluşturun.

Örnek yanıt

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

Yanıtta detection durumunu takip etmek için benzersiz image ID bulunur.

1. İlk sonuç analizden önce hazır olabilir

Çekirdek detection (result, final_result, confidence), analysis_results_status hâlâ pending iken hazır olabilir.

{
    "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. Poll etmeye devam

analysis_results_status pending'den çıkana kadar aynı id ile /query çağırın.

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 tamam

analysis_results_status ready olduğunda analysis_results agreement, imageTags, confidence, keyIndicators, detailedReasoning, visualPatterns ve recommendations 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": {
            "imageTags": [
                "person",
                "portrait",
                "outdoor",
                "vineyard",
                "smiling"
            ],
            "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 yoksa

analysis_results_status skipped, failed veya yoksa veya generate_analysis_details false ise çekirdek detection'ı nihai kabul edin.

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

"User verification failed" (403)

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

Çözüm:

1. API key'inizin doğru olduğunu doğrulayın
2. Hesabınızda API key'in aktif olduğunu kontrol edin
3. Gerekirse API key'i yeniden oluşturun

"Not enough credits" (403)

Neden: Görüntü işleme için yetersiz kredi

Çözüm:

1. /check-user-credits ile kalan kredinizi kontrol edin
2. Gerekirse ek kredi satın alın

"Input URL cannot be empty" (400)

Neden: Boş veya geçersiz URL gönderildi

Çözüm:

1. url girdinizin boş olmadığından emin olun
2. Görüntü adlarında başta/sonda boşluk bırakmayın
3. URL encoding'in doğru olduğunu kontrol edin

"Input email is empty" (400)

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

Çözüm:

1. URL gönderirken geçerli bir e-posta sağlayın
2. E-posta formatının doğru olduğunu kontrol edin

"Unsupported image type" (400)

Neden: Dosya formatı desteklenmiyor

Çözüm:

1. Desteklenen bir formata dönüştürün (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, GIF, SVG, PDF)
2. Dosya uzantısının doğru olduğunu kontrol edin

"File size is too small" (400)

Neden: Görüntü dosyası minimum boyutun altında

Çözüm:

1. Daha büyük bir görüntü dosyası kullanın (minimum 1KB)
2. Yükleme sırasında dosyanın bozulmadığını kontrol edin

"File size exceeds limit" (400)

Neden: Görüntü dosyası çok büyük

Çözüm:

1. Görüntüyü sıkıştırın veya yeniden boyutlandırın; limit dağıtıma göre ayarlanır (API hata mesajı MB cinsinden belirtir)
2. Farklı bir görüntü formatı deneyin

"Invalid file type" (400)

Neden: Dosya türü doğrulaması başarısız

Çözüm:

1. Dosyanın geçerli bir görüntü formatı olduğundan emin olun
2. Dosyanın bozuk olmadığını kontrol edin
3. MIME type ile dosya uzantısının eşleştiğini doğrulayın

Görüntü durumu "failed"

Neden: İşleme çeşitli nedenlerle başarısız oldu

Çözüm:

1. URL'nin desteklenen bir formatta olduğunu doğrulayın
2. Görüntü dosyasının geçerli ve bozuk olmadığını kontrol edin
3. Görüntünün boyut gereksinimlerini karşıladığından emin olun
4. Sorun sürerse destek ile iletişime geçin

"User not found"

Neden: Geçersiz user ID

Çözüm:

1. User ID'nin doğru olduğunu doğrulayın
2. Kullanıcı hesabının aktif olduğundan emin olun
3. Gerekirse yeniden kimlik doğrulayın

"File metadata could not be fetched" (500)

Neden: Yüklenen dosyaya erişilemiyor

Çözüm:

1. Dosyanın başarıyla yüklendiğini doğrulayın
2. Dosya URL'sinin erişilebilir olduğunu kontrol edin
3. Dosyayı yeniden yüklemeyi deneyin

"Image upload failed" (403/400)

Neden: Geçersiz veya süresi dolmuş pre-signed URL veya depolama sunucusu sorunu

Çözüm:

1. Pre-signed URL'i aldıktan sonra kısa sürede kullanın
2. Content-Type'ın dosya formatıyla eşleştiğini doğrulayın
3. Yüklemeden önce dosya adındaki boşlukları kaldırın
4. Gerekirse yeni pre-signed URL oluşturun

"Invalid pre-signed URL" (400)

Neden: Dosya adında boşluk veya süresi dolmuş/bozuk pre-signed URL

Çözüm:

1. Pre-signed URL istemeden önce dosya adındaki boşlukları kaldırın
2. Alfanumerik karakter, tire ve alt çizgi kullanın
3. Gerekirse yeni pre-signed URL oluşturun

"URL must point to a ZIP file" (400)

Neden: /bulk-upload'a verilen URL bir ZIP dosyasına işaret etmiyor

Çözüm:

1. get-presigned-url?file_name=images.zip (veya başka .zip adı) kullanın
2. Geçerli bir ZIP'i presigned URL'e yükleyin
3. bulk-upload isteğindeki url'nin o yüklenmiş ZIP'e işaret ettiğinden emin olun

"ZIP file too large" (400)

Neden: ZIP maksimum boyutu (100MB) aşıyor

Çözüm:

1. Görüntü sayısını azaltın veya sıkıştırın
2. Birden fazla bulk upload'a bölün

"Too many files" (400)

Neden: ZIP içinde 50'den fazla geçerli görüntü var

Çözüm:

1. ZIP başına 50 veya daha az görüntü kullanın
2. Birden fazla bulk upload'a bölün

"No valid images found in ZIP" (400)

Neden: ZIP'teki tüm dosyalar atlandı (desteklenmeyen format, çok küçük, geçersiz yol vb.)

Çözüm:

1. Desteklenen formatları kullanın (JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG)
2. Bulk içinde PDF desteklenmez
3. Her görüntü en az 1KB en fazla 10MB olmalı
4. Gizli dosyalar (. ile başlayan) ve path traversal (..) kullanmayın

"Document is not a bulk upload (image-zip) result" (400)

Neden: id bu yükleme türüyle eşleşmiyor (tek görüntü vs ZIP batch)

Çözüm:

1. Tek görüntü gönderimleri için /detect'ten dönen id'yi kullanın
2. ZIP gönderimleri için /bulk-upload'tan dönen id'yi kullanın