API Dokümantasyonu
ISO 27001SOC 2 CertifiedGDPR Compliant

YZ Ses Algılama API'si

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

Kod yazmadan denemek için FastAPI üç noktamızı ziyaret edin: https://detect-audio.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.

YZ Ses Algılayıcı

Algılama (3 Adımlı Süreç)

YZ Ses Algılama iş akışı aşağıdaki adımlardan oluşur:

  • On-imzali Yükleme URL'si Edinin
  • Sesi Yükleyin
  • Sesi Algılama İçin Gönderin

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

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

Desteklenen Dosya Formatları

MP3, WAV, M4A, FLAC, OGG, MP4

Önemli Not

On-imzali URL talep ederken ses dosyası adından boşlukları kaldırmak gereklidir.

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

Örnek İstek

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

Örnek Yanıt

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

2. Sesi Yükleyin

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

Önemli Not

Sesi yüklerken ses dosyası adından boşlukları kaldırmak gereklidir.

Örnek İstek

curl -X PUT 'https://audio-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...' \
  --header 'Content-Type: audio/<FILE_FORMAT - mp3, wav, m4a, flac, ogg, mp4>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.mp3' # Attachment

Dosya Boyutu Sınırları

  • Minimum dosya boyutu: 1KB
  • Maksimum dosya boyutu: 100MB

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. Sesi YZ Algılama İçin Gönderin

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

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

Örnek İstek

curl -X 'POST' \
  'https://detect-audio.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "<FILE_PATH>",
  "document_type": "Audio",
  "analyzeUpToSeconds": 60
}'

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

İsteğe Bağlı Parametreler

  • analyzeUpToSeconds: Başından itibaren N saniyeye kadar analiz et (varsayılan: 60)
  • document_type: Belge türü (varsayılan: 'Audio')
  • email: İşleme için isteğe bağlı e-posta

Örnek Yanıt

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

Yanıt, algılama durumunu izlemek için benzersiz bir kimlik içerir.

Algılama Durumunu ve Sonuçlarını Sorgulama

Durumu kontrol etmek ve sonuçları almak için kimlik ile /query üç noktasını kullanın.

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

Örnek İstek

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

Örnek Yanıt

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 0.873,
    "result_details": {
        "is_valid": true,
        "message": "processed",
        "original_duration": 123.45,
        "is_truncated": true,
        "truncated_duration": 60.0,
        "mean_ai_prob": 0.873,
        "individual_chunks_ai_prob": [0.81, 0.90, 0.91]
    }
}

Sonuç Detayları

  • is_valid: Ses dosyasının geçerli olup olmadığını gösterir (true/false)
  • message: İşleme mesaji
  • original_duration: Orijinal sesin saniye cinsinden süresi
  • is_truncated: Sesin analiz için kesilip kesilmedigini gösterir
  • truncated_duration: Kesilmişse analiz edilen süre
  • mean_ai_prob: Genel YZ olasılık skoru
  • individual_chunks_ai_prob: Parça başına YZ olasılık skorları

"status" alani şu değerlerden biri olacaktır: "pending" (işleme sıraya alındı), "analyzing" (YZ algılama devam ediyor), "done" (sonuçlar mevcut) veya "failed" (işleme başarısız oldu).

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-audio.truthscan.com/check-user-credits

Örnek İstek

curl -X 'GET' \
  'https://detect-audio.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
}

Sağlık Kontrolü

API sunucusunun sağlık durumunu kontrol edin.

GET https://detect-audio.truthscan.com/health

Örnek İstek

curl -X 'GET' \
  'https://detect-audio.truthscan.com/health' \
  -H 'accept: application/json'

Örnek Yanıt

{
    "status": "healthy"
}

Hatalar

Hataların çoğu, API'ye yanlış parametreler gönderilmesinden kaynaklanır. Her API çağrısının parametrelerini 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 ses işleme için yeterli kredi yok.
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: 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: Ses 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 analyzeUpToSeconds ile daha az ses analiz edin

Girdi Doğrulama Sorunları

"Desteklenmeyen dosya formati" (400)

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

Çözüm:

  1. Ses formatının desteklendiğinden emin olun (MP3, WAV, M4A, FLAC, OGG, MP4)
  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 100MB sınırını aşıyor

Çözüm:

  1. Sesi 100MB'in altina sıkıştırın veya dönüştürün
  2. Yüklemeden önce dosya boyutunu kontrol edin
  3. Mümkün olduğunda MP3 gibi daha verimli formatlar kullanın

İşleme Sorunları

"Ses işleme çok uzun surdu"

Neden: Ses işleme çok uzun surdu veya zaman aşımı olustu

Çözüm:

  1. Daha küçük bir ses dosyası veya daha kısa süre ile deneyin
  2. Yalnızca ilk saniyeleri analiz etmek için analyzeUpToSeconds kullanın
  3. Hizmetin yoğun yük altında olup olmadığını kontrol edin
  4. Birkac dakika sonra isteği yeniden deneyin

/query yanıtında "başarısız" durumu

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

Çözüm:

  1. Sesin minimum gereksinimleri karşılayıp karşılamadığını kontrol edin (1KB - 100MB)
  2. Sesin 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

Yükleme Sorunları

"Ses 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 ses 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

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.

Bize Ulaşın

API Sıkça Sorulan Sorular

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