واجهة إنشاء/جلب ملف WAV

آخر تحديث 2026-09-18 · فريق Suno-API

وصف نقطة النهاية

واجهة WAV تُنشئ أو تجلب عنوان صوت WAV دون فقدان لأغنية موجودة.

نقطة النهاية: POST /api/music/wav

الفوترة: مجاني. تُنشئ هذه الواجهة أو تجلب عنوان WAV لأغنية موجودة، ولا تخصم من الرصيد.

أوقات الانتظار والمهلات (مهم): هذه نقطة نهاية متزامنة — لا يُقبل الطلب إلا عند وصول الاستجابة. ووفق القياس، تعود معظم الطلبات في 1-3 ثوانٍ، ونحو 10% تتجاوز 30 ثانية، وأطولها نحو 230 ثانية. اضبط مهلة العميل على 300 ثانية أو أكثر؛ وعدم وصول استجابة لا يعني عدم التوليد، ولا تُعد المحاولة فوراً بعد انتهاء المهلة. وإن انقطع الاتصال فتحقق لاحقاً عبر GET /api/music/songs. راجع «أوقات الانتظار وإعدادات المهلة» في نظرة عامة على الواجهة الجديدة.

معاملات الطلب

Headers

معاملات الجسم

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

مثال الطلب

curl -X POST https://www.suno-api.io/api/music/wav \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "audioId": "clip_id",
    "maxAttempts": 24,
    "intervalSeconds": 5
  }'

الاستجابة

{
  "code": 200,
  "message": "success",
  "data": {
    "audioId": "clip_id",
    "status": "complete",
    "wavUrl": "https://media.code-go.com/assets/example.wav"
  }
}

ملاحظات

يختار الخادم إنشاء WAV والاستعلام عنه تلقائياً بناءً على سجل الأغنية؛ ولا يحتاج العميل إلى تقديم أي معلومات حساب.

الأغاني العادية والمسارات المفصولة تستخدم مسار توصيل الوسائط المُدار نفسه. ويقوم CN2 أولاً بتنزيل ملف WAV وكتابته على القرص، ولا يُعيد data.wavUrl في الاستجابة الناجحة إلا عنوان CDN مُداراً — ولا يُعيد أبداً عنوان مصدر مؤقتاً من Suno أو S3.

إذا كان أصل WAV بحالة ready موجوداً بالفعل فيُعاد استخدامه، دون طلبه من Suno مرة أخرى ودون نقل الملفات من جديد. أما WAV غير المُهيّأ فلا يُكشف كعنوان Suno/S3 عبر /api/music/query؛ بل يُهيّأ عند الطلب فقط بعد استدعاء هذه الواجهة أو واجهة التنزيل الموحّدة.

⚠️ صلاحية عنوان WAV: 7 أيام — احفظه في الوقت المناسب. عنوان data.wavUrl المُعاد يوفّره تخزين الكائنات في المنصة وينتهي افتراضياً بعد 7 أيام (تُستعاد الملفات ويعيد العنوان القديم الخطأ 404). احفظ ملف WAV في مساحتك الخاصة خلال هذه المدة؛ وبعد انتهائها استدعِ هذه الواجهة مجدداً للحصول على عنوان صالح جديد.

إذا كان مورد الأغنية غير متاح مؤقتاً، تُعيد الواجهة 409. أعد المحاولة لاحقاً؛ ولن يُعيد الخادم عناوين مؤقتة غير مستقرة.