توثيق API
ISO 27001SOC 2 CertifiedGDPR Compliant

واجهة كشف الصوت بالذكاء الاصطناعي

توثيق كامل لدمج واجهة كشف الصوت بالذكاء الاصطناعي من TruthScan في تطبيقاتك.

جرّب بدون كود عبر نقطة نهاية FastAPI: https://detect-audio.truthscan.com/docs

المصادقة

تستخدم TruthScan مفاتيح API للسماح بالوصول. يمكنك الحصول على مفتاحك في أعلى الصفحة في بوابة المطورين.

تتوقع TruthScan تضمين مفتاح API في جميع الطلبات إلى الخادم في جسم طلب يشبه ما يلي:

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

يجب استبدال YOUR API KEY GOES HERE بمفتاحك الشخصي.

كاشف الصوت بالذكاء الاصطناعي

الكشف (3 خطوات)

سير عمل كشف الصوت بالذكاء الاصطناعي:

  • الحصول على رابط رفع موقّع مسبقاً
  • رفع الملف الصوتي
  • إرسال الصوت للكشف

1. الحصول على رابط رفع موقّع مسبقاً

اطلب رابطاً موقّعاً مسبقاً من واجهة API. يتيح لك رفع ملف الصوت بأمان إلى خادم التخزين.

تنسيقات الملفات المدعومة

MP3, WAV, M4A, FLAC, OGG, MP4

ملاحظة مهمة

يجب إزالة المسافات من اسم ملف الصوت عند طلب الرابط الموقّع.

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

مثال طلب

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

مثال استجابة

{
  "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. رفع الصوت

استخدم 'presigned_url' المُرسل لرفع الصوت عبر طلب PUT. اضبط نوع المحتوى حسب تنسيق الصوت.

ملاحظة مهمة

يجب إزالة المسافات من اسم الملف عند الرفع.

مثال طلب

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

حدود حجم الملف

  • الحد الأدنى لحجم الملف: 1 ك.ب
  • الحد الأقصى لحجم الملف: 100 م.ب

حافظ على اتساق التنسيق أثناء الرفع. الرفع الناجح يعيد رمز الحالة 200.

3. إرسال الصوت للكشف

بعد الرفع، أرسل الصوت للكشف باستخدام 'file_path' من الخطوة السابقة.

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

مثال طلب

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' إلى المسار من الاستجابة في خطوة «الحصول على رابط رفع موقّع».

معاملات اختيارية

  • analyzeUpToSeconds: تحليل حتى N ثانية من البداية (افتراضي: 60)
  • document_type: نوع المستند (افتراضي: 'Audio')
  • email: بريد إلكتروني اختياري للمعالجة

مثال استجابة

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

تتضمن الاستجابة معرفاً فريداً لمراقبة حالة الكشف.

الاستعلام عن حالة الكشف والنتائج

للتحقق من الحالة وجلب النتائج، استخدم نقطة /query مع المعرف.

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

مثال طلب

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

مثال استجابة

{
    "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]
    }
}

تفاصيل النتيجة

  • is_valid: هل صالح ملف الصوت (true/false)
  • message: رسالة المعالجة
  • original_duration: مدة الصوت الأصلية بالثواني
  • is_truncated: هل قُصّ الصوت للتحليل
  • truncated_duration: المدة المحلّلة عند القص
  • mean_ai_prob: درجة احتمال الذكاء الاصطناعي الإجمالية
  • individual_chunks_ai_prob: درجات احتمال لكل مقطع

حقل "status" يكون أحد: "pending" (في الانتظار)، "analyzing" (جاري الكشف)، "done" (النتائج جاهزة)، أو "failed" (فشل المعالجة).

التحقق من أرصدة المستخدم

تقبل نقطة النهاية مفتاح apikey عبر الرأس وتعيد تفاصيل الأرصدة.

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

مثال طلب

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'

مثال استجابة

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

فحص الصحة

التحقق من حالة خادم واجهة API.

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

مثال طلب

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

مثال استجابة

{
    "status": "healthy"
}

الأخطاء

تنجم معظم الأخطاء عن معاملات غير صحيحة. راجع معاملات كل طلب وجرّب نموذج الكود المرفق.

رموز الخطأ العامة تتوافق مع معيار REST:

رمز الخطأالمعنى
400طلب سيء — الطلب غير صالح.
403ممنوع — مفتاح API غير صالح أو أرصدة غير كافية لمعالجة الصوت.
404غير موجود — المورد غير موجود.
405الطريقة غير مسموحة — محاولة وصول بطريقة غير صالحة.
406غير مقبول — طُلب تنسيق ليس JSON.
410زال — أُزيل المورد من هذا المسار.
422جسم طلب غير صالح — التنسيق خاطئ أو معاملات ناقصة.
429طلبات كثيرة جداً — أبطئ وتيرة الطلبات.
500خطأ داخلي في الخادم — حدثت مشكلة. أعد المحاولة لاحقاً.
503الخدمة غير متاحة — صيانة مؤقتة. حاول لاحقاً.

مشاكل شائعة وحلول

مشاكل المصادقة

"User verification failed" (403)

السبب: مفتاح API غير صالح أو منتهٍ

الحل:

  1. تحقق من صحة مفتاح API
  2. تأكد أن المفتاح نشط في حسابك
  3. جرّب إعادة إنشاء مفتاح API

"Not enough credits" (403)

السبب: أرصدة غير كافية لمعالجة الصوت

الحل:

  1. تحقق من الأرصدة المتبقية عبر /check-user-credits
  2. اشترِ أرصدة إضافية عند الحاجة
  3. استخدم analyzeUpToSeconds لتحليل مدة أقصر واستهلاك أقل

مشاكل التحقق من المدخلات

"Unsupported file format" (400)

السبب: تنسيق صوت غير مدعوم أو غير صالح

الحل:

  1. تأكد أن التنسيق مدعوم (MP3, WAV, M4A, FLAC, OGG, MP4)
  2. تأكد أن الملف غير تالف
  3. تحقق من رأس Content-Type عند الرفع

"File too large" (400)

السبب: حجم الملف يتجاوز حد 100 م.ب

الحل:

  1. اضغط الملف أو حوّله ليكون أقل من 100 م.ب
  2. تحقق من الحجم قبل الرفع
  3. استخدم تنسيقات أكثر كفاءة مثل MP3 عند الإمكان

مشاكل المعالجة

"Audio processing took too long"

السبب: انتهت مهلة المعالجة أو استغرقت وقتاً طويلاً

الحل:

  1. جرّب ملفاً أصغر أو مدة أقصر
  2. استخدم analyzeUpToSeconds لتحليل الثواني الأولى فقط
  3. تحقق إن كان الخادم تحت حمل عالٍ
  4. أعد المحاولة بعد بضع دقائق

الحالة "failed" في استجابة /query

السبب: فشلت المعالجة لأسباب متعددة

الحل:

  1. تأكد أن الصوت يلبي الحد الأدنى (1 ك.ب - 100 م.ب)
  2. تحقق من التنسيق المدعوم
  3. تأكد من اكتمال الرفع قبل الإرسال للكشف
  4. اتصل بالدعم إن استمرت المشكلة

مشاكل الرفع

"Audio upload failed" (403/400)

السبب: رابط موقّع مسبقاً غير صالح أو منتهٍ، أو مشكلة في التخزين

الحل:

  1. استخدم الرابط الموقّع فور استلامه (قد ينتهي)
  2. تحقق من رأس Content-Type المناسب للتنسيق
  3. أزل المسافات من اسم الملف قبل الرفع
  4. ولّد رابطاً موقّعاً جديداً إن انتهى القديم

"Invalid pre-signed URL" (400)

السبب: اسم ملف يحتوي مسافات أو رابط موقّع منتهٍ/تالف

الحل:

  1. أزل جميع المسافات من اسم الملف قبل طلب الرابط
  2. استخدم أحرفاً وأرقاماً وشرطات وشرطات سفلية فقط
  3. ولّد رابطاً موقّعاً جديداً عند الحاجة

تحتاج مساعدة؟

لمزيد من المعلومات حول واجهة API أو الدعم الفني، اتصل بنا.

اتصل بنا

الأسئلة الشائعة لواجهة API

إجابات على الأسئلة الأكثر شيوعاً حول واجهة كشف الصوت بالذكاء الاصطناعي.