واجهة رفع الصوت المصدر

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

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

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

نقطة النهاية: POST /api/music/upload-source

الفوترة: مجاني. هذه الواجهة ترفع الصوت المصدر فقط، ولا تبدأ مهمة توليد.

الاستخدام الموصى به: هذه هي الخطوة 1 من «الكوفر بخطوتين». ارفع الصوت أولاً عبر هذه الواجهة (مجاناً، ويمكنك إعادة المحاولة في أي وقت عند الفشل) واحفظ clip_id المُعاد؛ وبعد التأكد من نجاح الرفع (status في حالة مكتملة)، استدعِ واجهة الكوفر من مقطع مصدر لبدء الكوفر — جسم ذلك الطلب لا يتجاوز بضع مئات من البايتات، ولذلك لا يمكن أن يُقطع أثناء النقل لأن الصوت كبير جداً. ومقارنة بواجهة الخطوة الواحدة الرفع ثم الكوفر، فإن هذا التقسيم أكثر ثباتاً عندما يكون الصوت كبيراً أو الشبكة غير مستقرة أو الحاجة إلى إعادة استخدام المادة نفسها عدة مرات (التمديد / الاستبدال / الفصل).

نصائح لرفع الملفات الكبيرة

بعد انتهاء الرفع، تأكد دائماً من أن status في الاستجابة أصبح حالة مكتملة واحفظ clip_id قبل الانتقال إلى الخطوة 2؛ وفشل الرفع لا يُحتسب مالياً ولا ينشئ مهمة توليد، فما عليك سوى إعادة المحاولة.

تحقق من file_url قبل الرفع

يقوم خادم المنصة بتنزيل file_url بنفسه، وليس المتصفح. فتح الرابط في متصفحك لا يثبت أن خادم الإنتاج يستطيع الوصول إليه.

استخدم رفع multipart مع الحقل file للملفات المحلية. لا تستخدم file_url لعناوين ByteDance أو الروابط الموقعة المؤقتة إلا إذا كانت متاحة للعامة وما زالت صالحة عند إرسال الطلب.

من خادم عام، نفّذ الأمر التالي قبل إرسال طلب الرفع:

curl -L --max-time 30 -D - -o /dev/null "https://example.com/source.mp3"

يجب أن ينتهي طلب GET إلى HTTP 200، وأن يكون النوع audio/* أو نوع صوت صحيح، وأن يحتوي على بيانات غير فارغة. إذا انتهى إلى صفحة تسجيل دخول أو HTML، أو أعاد 401 أو 403 أو 404 أو 410، فلن تستطيع المنصة تنزيل الملف.

رسالة file_url download failed: HTTP 404 تعني عادة أن الرابط انتهت صلاحيته أو أن الملف حُذف أو أن المعاملات ناقصة.

هذا الرفع مجاني. عند فشل تنزيل file_url لا يتم إنشاء clip_id أو مهمة أغنية ولا يتم استدعاء نموذج توليد ولا يتم الخصم، لذلك لا حاجة إلى استرداد.

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

Headers

لطلبات JSON:

لا تضبط Content-Type يدوياً في طلبات multipart؛ فالعميل يُنشئه تلقائياً.

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

مثال طلب JSON

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "upload_type": "file_upload"
  }'

مثال طلب multipart

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.mp3" \
  -F "file_name=source.mp3" \
  -F "upload_type=file_upload" \
  -F "model=suno-v6"

import requests

with open("source.mp3", "rb") as audio:
    response = requests.post(
        "https://www.suno-api.io/api/music/upload-source",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        data={
            "file_name": "source.mp3",
            "upload_type": "file_upload",
            "model": "suno-v6",
        },
        files={"file": ("source.mp3", audio, "audio/mpeg")},
        timeout=300,
    )

response.raise_for_status()
print(response.json())

الاستجابة

{
  "clip_id": "uploaded_clip_id",
  "status": "complete",
  "title": "source.mp3",
  "image_url": "https://...",
  "audio_url": "https://...",
  "display_tags": "pop, vocal",
  "inferred_description": "uploaded source audio",
  "clip_metadata": {}
}