دليل البدء لتنقية الصوت

تنقية الصوت تزيل الهدير المنخفض، وتضغط الديناميكية، وتوازن مستوى الصوت، وتحدّ من القمم في التسجيل. ينظّف هذا الدليل ملفًا قصيرًا باستدعاء متزامن واحد، ثم يقرأ رابط الملف المنقّى، ويضبط أداة التنقية، ويعرض مهامك السابقة.

ما تحتاج إليه

• مفتاح API. راجع احصل على مفتاح API. إذا كان المفتاح يقيّد الخدمات، فيحتاج إلى وصول على تنقية الصوت.
• الرابط الأساسي. راجع الرابط الأساسي.
• رصيد في مساحة العمل. يُؤخذ الخصم قبل بدء التنقية. راجع الرصيد.
• ملف صوتي مدته 10 دقائق أو أقل، وحجمه 150 ميجابايت أو أقل، بصيغة MP3 أو WAV أو FLAC أو OGG/Opus.

الخطوات

الخطوة 1: نظّف ملفًا

أرسل الملف كجزء file من طلب multipart/form-data إلى POST https://api.echonova.ai/v1/sound-cleaning. ينتظر الاستدعاء أداة التنقية، ويعيد النتيجة في الاستجابة. لا توجد نقطة غير متزامنة.

curl -X POST "https://api.echonova.ai/v1/sound-cleaning" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@noisy.wav;type=audio/wav"

import requests

with open("noisy.wav", "rb") as audio:
    response = requests.post(
        "https://api.echonova.ai/v1/sound-cleaning",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"file": ("noisy.wav", audio, "audio/wav")},
    )
print(response.json())

import { readFile } from 'node:fs/promises';

const formData = new FormData();
formData.append('file', new Blob([await readFile('noisy.wav')], { type: 'audio/wav' }), 'noisy.wav');

const response = await fetch('https://api.echonova.ai/v1/sound-cleaning', {
  method: 'POST',
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
  body: formData,
});
console.log(await response.json());

الخطوة 2: اقرأ النتيجة

تعيد الاستدعاءات الناجحة HTTP 200 والغلاف المعتاد. النتيجة موجودة في data:

{
  "success": true,
  "statusCode": 200,
  "errorMessage": null,
  "data": {
    "id": "66e3f2a1c9d4b8a1f0e12345",
    "status": "completed",
    "fileName": "noisy.wav",
    "outputUrl": "https://storage.example.com/cleaned/66e3f2a1c9d4b8a1f0e12345.wav?signature=abc",
    "durationSeconds": 12,
    "creditsConsumed": 207,
    "metrics": {
      "sampleRate": 48000,
      "integratedLufs": -16.1,
      "truePeakDbfs": -1
    },
    "createdAt": "2026-10-11T10:21:04.512Z"
  }
}

الملف المنقّى دائمًا بصيغة WAV. الرابط ينتهي، لذا نزّل الملف عند استلامه، أو اقرأ المهمة لاحقًا للحصول على رابط جديد.

الخطوة 3: اضبط أداة التنقية

ثمانية حقول نموذج اختيارية تغيّر طريقة عمل أداة التنقية. إذا تركتها، تستخدم الأداة قيمها الافتراضية. القيمة خارج مداها تُرفض بـ 400.

curl -X POST "https://api.echonova.ai/v1/sound-cleaning" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@noisy.wav;type=audio/wav" \
  -F "targetLufs=-18" \
  -F "cutoffFreq=120"

الخطوة 4: اعرض مهامك

GET https://api.echonova.ai/v1/sound-cleaning/jobs يعيد مهام API في مساحة العمل، الأحدث أولًا، بواقع 20 في الصفحة. أضف offset وlimit (من 1 إلى 100) للتنقل بين الصفحات. GET https://api.echonova.ai/v1/sound-cleaning/jobs/{jobId} يعيد مهمة واحدة برابط outputUrl جديد.

curl "https://api.echonova.ai/v1/sound-cleaning/jobs?offset=0&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

يرى هذه المهام أي مفتاح في مساحة العمل له وصول إلى تنقية الصوت، أيًا كان المفتاح الذي أنشأها. المهام المُنشأة من البوابة لا تظهر هنا.

ما يحدث بعد ذلك

• السعر 1,000 credits لكل دقيقة من الصوت، يُحسب بالثانية، بحد أدنى ثانية واحدة. تقيس API الصوت بعد فك الترميز، لا بالاعتماد على header الملف، لذا ملف مدته 12.4 ثانية يكلّف 207 credits (206.67 مقرّبة إلى رصيد كامل). راجع الرصيد.
• يُخصم الرصيد من مساحة العمل قبل بدء التنقية، ويُعاد إذا فشلت. يُفحص عدّاد الاستخدام الخاص بالمفتاح أولًا أمام حد الرصيد الخاص به؛ أي استدعاء يتجاوز الحد يُرفض بـ 429 ولا يُخصم شيء.
• كل استدعاء ينشئ مهمة، فيبقى العمل مدرجًا تحت مفتاحك.

الحدود

حل المشكلات

400 File is required

الطلب لم يحمل جزءًا اسمه file. تحقق من اسم الحقل، ومن أن الطلب من نوع multipart/form-data.

400 Unsupported audio format. Sound cleaning accepts MP3, WAV, FLAC or OGG/Opus.

الامتداد أو Content-Type ليس واحدًا من الصيغ الأربع، أو أنهما لا يتطابقان. الملف .wav المرسل بنوع audio/mpeg يُرفض.

400 Audio exceeds the 10-minute limit.

الصوت أطول من 10 دقائق. قسّمه إلى مقاطع مدة كل منها 10 دقائق أو أقل، وأرسل كل مقطع.

400 targetLufs must not be greater than -6

حقل ضبط خارج مداه في الجدول الوارد في الخطوة 3، والرسالة تسمّي الحقل والحد. أما حقل النموذج الذي ليس من الحقول الثمانية، مثل volume، فيُرفض بـ property volume should not exist.

413 File too large

الملف المرفوع أكبر من 150 ميجابايت. يُقطع الطلب قبل قراءة الملف.

503 Sound cleaning is temporarily unavailable. Please try again.

تعذّر الوصول إلى أداة التنقية. يُعاد الرصيد. أعد المحاولة مرة واحدة.

404 Clean Job not found

معرّف jobId غير موجود، أو يتبع مساحة عمل أخرى، أو أُنشئ من البوابة.

403 This API key does not have access to Sound Cleaning services

المفتاح يقيّد الخدمات، وتنقية الصوت ليست منها. اضغط تعديل على المفتاح في البوابة، وفعّل تنقية الصوت. المفاتيح التي ليس لها قيد على الخدمات تستطيع استخدامها من الآن.

402 Insufficient subscription balance

رصيد مساحة العمل لا يغطي الخصم. لم يعمل شيء.

الأسئلة الشائعة

هل أستطيع تنقية ملف أطول من 10 دقائق؟

ليس عبر API حاليًا. قسّمه إلى مقاطع مدة كل منها 10 دقائق أو أقل، وأرسل كل مقطع.

هل توجد نقطة غير متزامنة؟

لا. تجيب أداة التنقية في الاستدعاء نفسه، لذا النقطة متزامنة فقط.

صفحات ذات صلة

• تنقية الصوت
• عرض مهام تنقية الصوت
• تفاصيل مهمة تنقية الصوت
• الرصيد
• حدود معدل الطلبات
• نقِّ تسجيلًا