واجهة الرفع المعزّز

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

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

الرفع المعزّز يرسل ملفاً صوتياً محلياً؛ فينفّذ النظام تحسيناً في الخلفية ويُنتج أغنية كاملة قابلة للتشغيل. ويعيد نداء الإرسال معلومات المهمة فوراً، ويستعلم العميل من واجهة الاستعلام لمتابعة التقدّم.

واجهة الإرسال: POST /api/music/enhanced-upload

استعلام مهمة واحدة: GET /api/music/enhanced-upload/:id

إلغاء المهمة: POST /api/music/enhanced-upload/:id/cancel

استعلام القائمة: GET /api/music/enhanced-upload

الفوترة: 10 يوان لكل طلب، تُخصم مقدماً بالسعر الثابت suno-enhanced-upload. وإذا فشلت المهمة أو أُلغيت في المرحلة المسموح بها، يُعاد المبلغ المخصوم مقدماً تلقائياً. والمبلغ المخصوم فعلاً يتبع إعداد الأسعار الحالي في لوحة الإدارة.

تسلسل الاستدعاء

1. استدعِ POST /api/music/enhanced-upload لرفع الملف الصوتي.
2. احفظ task_id المُعاد.
3. استدعِ GET /api/music/enhanced-upload/:id لمعرفة التقدّم والنتيجة.
4. بعد أن يُنهي Suno العرض النهائي، تستخدم الخدمة حساب Suno المرتبط بتلك المهمة لاستدعاء واجهة التنزيل المصرّح بها في Studio وكتابة ملف MP3 في خدمة وسائط CN2.
5. لا تصبح المهمة completed إلا بعد جهوزية أصل CN2، وعندها يُقرأ عنوان الصوت من CDN في audio_url من الاستجابة.

/api/forbidden عنوان بديل قد يظهر في بيانات Suno Studio الوصفية؛ وهو ليس مورداً قابلاً للتشغيل أو التنزيل. ولا يُعاد للعميل أبداً ولا يُستخدم أساساً للحكم على الاكتمال. وإذا انتهى العرض لكن CN2 ما زال يجهّز، تستمر الواجهة في إرجاع processing ولا تُعيد audio_url؛ وعلى العميل مواصلة الاستعلام وعدم اعتبار العنوان الفارغ فشلاً.

إرسال رفع معزّز

Headers

معاملات النموذج

مثال الطلب

يستخدم المثال أدناه نفس طريقة الاستدعاء كما في التحقق على بيئة الإنتاج، لكن مفتاح API استُبدل بقيمة بديلة.

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

الاستجابة

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

استعلام مهمة واحدة

مثال الطلب

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

مثال الاستجابة أثناء المعالجة

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

مثال الاستجابة عند الاكتمال

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

إلغاء المهمة

لا يمكن الإلغاء إلا ما دامت المهمة وسير العمل في الخلفية في مرحلة queued. وبعد دخول المهمة في leasing أو running أو processing أو اكتمالها، لا يمكن إلغاؤها.

مثال الطلب

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

الاستجابة

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

وإذا كانت المهمة قد بدأت المعالجة، فستعيد الواجهة:

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

استعلام قائمة المهام

تُعيد واجهة القائمة مهام الرفع المعزّز الخاصة بمستخدم مفتاح API الحالي فقط، ولا تختلط بمهام التوليد العادي أو الكوفر أو التمديد.

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

مثال الطلب

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

الاستجابة

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

شرح حقول الاستجابة

ملاحظات

• تدعم الواجهة حالياً رفع الملفات بصيغة multipart فقط، ولا تدعم file_url أو file_base64 بصيغة JSON.
• الحد الأقصى لحجم الملف المرفوع 80 ميجابايت.
• واجهة الإرسال غير متزامنة: استجابة queued تعني أن المهمة دخلت قائمة الانتظار، ولا تعني أن الصوت قد اكتمل.
• الإلغاء ينطبق فقط على المهام التي لم تبدأ المعالجة؛ وبعد بدء المعالجة لا يتوقف سير عمل حساب المنصة.
• لا تُظهر مفاتيح API الحقيقية في كود العميل.

بدء الكوفر بعد اكتمال الرفع المعزّز

بعد اكتمال الرفع المعزّز يمكنك استخدام النتيجة كمقطع مصدر واستدعاء POST /api/music/generate-from-source لبدء الكوفر.

تنبيه: الكوفر واجهة متزامنة — ولا يُقبل الطلب إلا عند وصول الاستجابة، وقد يصل الانتظار في حالات مقيسة إلى نحو 230 ثانية. اضبط مهلة العميل على 300 ثانية أو أكثر، ولا تُعد المحاولة فوراً بعد انتهاء المهلة. راجع «أوقات الانتظار وإعدادات المهلة» في نظرة عامة على الواجهة الجديدة.

استعلم أولاً GET /api/music/enhanced-upload/:id حتى يصبح task.status هو completed. وعندها:

• task.song_id هو معرّف الأغنية الحقيقي وهو أيضاً sourceClipId الذي تحتاجه واجهة الكوفر؛
• يُستحسن تمرير task.audio_url كـ sourceAudioUrl، ليتعامل الخادم مع حالة اختلاف المقطع المصدر وحساب التنفيذ؛
• task.task_id هو مجرد معرّف مهمة الرفع المعزّز ولا يصلح كـ sourceClipId؛
• pending:enhanced-upload:* معرّف بديل خاص بمرحلة المعالجة ولا يصلح للكوفر.

عند بدء الكوفر، استخدم مفتاح API نفسه المستخدم في الرفع المعزّز، وركّب الطلب وفق مطابقة الحقول أدناه.

املأ بقية المعاملات (الكلمات والأسلوب والعنوان والنموذج) وفق واجهة الكوفر من مقطع مصدر. وبعد أن تُعيد واجهة الكوفر clips[].song_id الجديد، استخدم POST /api/music/query للاستعلام عن حالة التوليد والصوت النهائي.