نظرة عامة على وثائق Suno API

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

سجّل ببريد إلكتروني وستتمكن من إنشاء مفتاح API. كل عملية توليد تكلف 0.6 يوان وتعيد مقطوعتين، وتشمل تنزيل MP3/WAV وأغاني الكوفر و Extend وفصل المسارات واستنساخ الصوت. عنوان URL الأساسي: https://www.suno-api.io.

تسرد هذه الصفحة النماذج المتاحة حالياً، وكل نقاط النهاية الخاصة بالتوليد والتحرير، وطريقة الفوترة، وترتيب القراءة الموصى به. إذا كانت هذه أول مرة تربط فيها الخدمة، فاقرأ الصفحة من أعلى إلى أسفل؛ كما تجد في هذه الصفحة معالجة الأخطاء 401/403/429.

إجابات سريعة

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

كم تكلفة الطلب الواحد؟ عملية التوليد الواحدة تكلف 0.6 يوان وتعيد مقطوعتين. أما استعلامات الحالة و WAV والكلمات المزوّدة بعلامات زمنية واقتراحات البرومبت فمجانية.

ما النماذج المدعومة؟ suno-v6 (الافتراضي) و suno-v6-wild و suno-v6-mini. وقد أُلغيت نماذج التوليد القياسية v5.5 وما قبلها؛ والأعمال الموجودة لا تتأثر.

ما عنوان URL الأساسي؟ https://www.suno-api.io، مع الترويسة Authorization: Bearer YOUR_API_KEY.

النماذج المتاحة حالياً

نماذج العملاء لتوليد الأغاني القياسي هي suno-v6 و suno-v6-wild و suno-v6-mini. وعند حذف الحقل model سيُستخدم suno-v6.

النماذج القياسية suno-v2 و suno-v3 و suno-v3-5 و suno-v4 و suno-v4-5 و suno-v4-5-all و suno-v4-5-plus و suno-v5 و suno-v5-5 أُلغيت. قد تُظهر المهام القديمة هذه الأسماء؛ لكنها بيانات تاريخية، وليست دليلاً على إمكان استخدام النموذج في طلبات جديدة. وفصل المسارات استثناء — راجع واجهة فصل المسارات (فصل الغناء عن الموسيقى).

المصادقة

كل نقطة نهاية عامة تعتمد مفتاح API تستخدم مجموعة الترويسات نفسها:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

عنوان URL الأساسي:

https://www.suno-api.io

أعراف المعاملات العامة

• قيمة number في جسم الطلب يجب أن تكون رقماً بصيغة JSON، لا نصاً بنسبة مئوية. شدة 50% تُكتب 0.5، ولا تُكتب أبداً 50 أو 50%.
• قيمة boolean يجب أن تكون true أو false. ولا تستخدم 0 أو 1 بديلاً عنهما.
• الحقول المعلّمة بـ "لا" يمكن حذفها تماماً. وإذا لم تكن متأكداً من وظيفة معامل ما، فاتركه ليعمل النظام بسلوكه الافتراضي؛ ولا ترسل نصاً فارغاً أو null أو 0 بدل "غير مُرسَل"، لأن 0 قيمة صحيحة لبعض الحقول الرقمية.
• أسماء الحقول حساسة للإملاء. وكل صفحة نقطة نهاية تسرد الاسم الموصى به والأسماء البديلة المتوافقة؛ فأرسلها كما يظهر في جدول المعاملات تماماً. وحيث تذكر الوثائق أن snake_case و camelCase مقبولان، لا ترسلهما معاً في الطلب نفسه.
• كل حقل مدة ينتهي بـ _s أو Seconds يُقاس بالثواني ويقبل الأعداد العشرية. أما طوابع Unix الزمنية فتُشرح بشكل منفصل، بما في ذلك إن كانت بالثواني أو بالملي ثانية.
• المعرّف الذي يبدأ بـ pending: هو حجز مؤقت من المنصة، وليس song_id حقيقياً. لا تستخدمه إلا حيث تذكر نقطة النهاية دعم الحجز المؤقت صراحةً؛ وفي غير ذلك انتظر song_id الحقيقي.

حدود حقول النص

تجاوز حد النص يعيد HTTP 400 مباشرة: فلا يجري أي توليد، ولا خصم مسبق، ولا يُنشأ أي سجل مهمة. والعدّ بالأحرف بترميز Unicode (الحرف الصيني الواحد يُحسب 1) وتُحسب المسافات في البداية والنهاية.

يذكر الحقل message أي حقل تجاوز الحدّ والطول المقيس، ويكفي هذان الرقمان لتقصيره:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

ينطبق على: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

وهناك استثناء واحد: الحقل description في POST /api/music/sounds محدود بـ 100 حرف، لأن مسار المؤثرات الصوتية يستخدم الحد الأقصر الخاص بالمنصة.

التوليد اللامتزامن وعناوين الملفات الصوتية

نقاط نهاية توليد الموسيقى تعمل افتراضياً بشكل لامتزامن. وعندما يحمل الرد الأول قيمة status تساوي pending أو submitted أو processing، فإن كون audio_url أو video_url أو cover_url فارغاً أمر طبيعي ولا يعني فشل المهمة. احفظ song_id الحقيقي (أو client_request_id الذي أعادته نقطة النهاية) ثم استدعِ نقطة النهاية المطابقة للاستعلام؛ ولا تقرأ عنوان الصوت وتنزّله إلا بعد اكتمال الحالة.

⚠️ عناوين الملفات الصوتية تنتهي صلاحيتها بعد 7 أيام — انقل ملفاتك في الوقت المناسب

تُقدَّم audio_url و wav_url و video_url والعناوين التي تعيدها نقاط نهاية التنزيل من التخزين الكائني للمنصة، وتنتهي صلاحيتها افتراضياً بعد 7 أيام (تُعاد الملفات للتخزين الدوري؛ والعنوان القديم يعيد 404 أو يفشل التنزيل).

• خلال هذه الأيام السبعة، انقل الملفات إلى مخزنك الخاص (تخزينك الكائني أو شبكة توصيل محتوى أو قرص خادم). لا تعتبر عناويننا روابط طويلة الأجل.
• العنوان المنتهي الصلاحية لا يحتاج إلى إعادة توليد الأغنية ولا يكلف شيئاً إضافياً: استدعِ واجهة استعلام الأغنية (أو واجهة تنزيل الوسائط) مرة أخرى للحصول على عنوان جديد صالح لتلك الأغنية.

أوقات الانتظار وإعدادات المهلة

نقاط نهاية التوليد متزامنة: فلا يُقبل الطلب ويُسلَّم إلى المنصة للتوليد إلا عند وصول الرد. وقبل ذلك يجب على الخدمة أن تجدّول حساباً وأن تجتاز فحص الأمان الإلزامي، ولا يوجد رد وسيط — ولا تستطيع أي نقطة نهاية أخرى رؤية الطلب. لذا فإن الدليل الموثوق الوحيد على أن "شيئاً قد وُلِّد" هو الرد نفسه، لا أي شيء تلاحظه أثناء الانتظار.

أوقات الانتظار المقيسة (عائلة /api/music/create في بيئة الإنتاج، من 2026-09-18 إلى 2026-09-20)

• نحو 10% من الطلبات تستغرق أكثر من 30 ثانية، ونحو 1% تستغرق من دقيقة إلى دقيقتين. والطلب البطيء يعني عادةً أن هذه المحاولة كان عليها اجتياز فحص أمان أولاً.
• حقول الطلب وشكل الرد ورموز الخطأ والفوترة لم تتغير، لذا لا يحتاج التكامل القائم إلا إلى رفع مهلة العميل — دون أي تغيير آخر في الشيفرة.

متطلبات التكامل

1. اضبط مهلة العميل على 300 ثانية أو أكثر. فالعميل الذي يستخدم 30 أو 60 أو 120 ثانية سيفصل الاتصال أثناء الانتظار.
2. عدم وجود رد لا يعني عدم وجود توليد. عند حدوث مهلة أو انقطاع الاتصال قد يكون الطلب قد قُبل وهو قيد التوليد فعلاً.
3. لا تُعد المحاولة فوراً بعد انتهاء المهلة: فالإرسال المكرر ينشئ طلباً ثانياً ويُحاسَب عليه مرة أخرى.
4. إذا انقطع الاتصال، فاسرد أغانيك عبر GET /api/music/songs (الأحدث أولاً) بعد قليل — فالطلبات المقبولة تظهر بشكل طبيعي. ولا تُعد الإرسال إلا بعد التأكد من أن الطلب غير موجود فعلاً.
5. عند الإبلاغ عن مشكلة، أرفق ترويسة الرد X-Oneapi-Request-Id حتى يمكن تحديد الطلب نفسه مباشرةً.

لا تريد إبقاء اتصال طويل؟ استخدم وضع إيصال القبول. يدعم POST /api/music/create و POST /api/music/create/custom إيصال قبول اختيارياً: أضف "accept_mode": "async" إلى جسم الطلب (أو الترويسة X-Accept-Mode: async) فتعيد نقطة النهاية 202 فوراً مع رقم إيصال بينما يستمر التوليد في الخلفية؛ ثم استعلم بـ GET /api/music/requests/{request_id} عن التقدم. وبذلك لا يخطئ عميلٌ مهلة انتظاره بضع عشرات من الثواني في تفسير "لا رد" على أنه "لا توليد"، ولا يمكن أن يُحاسَب مرتين بسبب إعادة المحاولة. راجع "وضع إيصال القبول" في واجهة التوليد بالوضع المبسّط.

للمرجعية: يستخدم python requests القيمة timeout=300، ويستخدم urllib الصيغة urlopen(..., timeout=300)، ويستخدم Node الصيغة req.setTimeout(300000)، ويستخدم curl الخيار --max-time 300.

قائمة نقاط النهاية الموصى بها

مسارات /api/voice/clone/* و /api/music/generate-with-voice هي سلسلة استنساخ الصوت من الجيل الأول ولا يُوصى بها للتكاملات الجديدة؛ استخدم بدلاً منها 【موصى به】 واجهة الملف الصوتي الشخصي.

المعاملات المتقدمة: Max Mode و Variety

تدعم نقاط نهاية التوليد هذين المعاملين الاختياريين (وتركهما يحافظ على السلوك والسعر السابقين):

يدعم هذين المعاملين كلٌّ من: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• السعر المضاعف عملياً: نقطة نهاية تكلف 0.6 يوان لكل طلب تصبح 1.2 يوان مع max_mode؛ والتوليد بصوت مختار يكلف 1.2 يوان لكل طلب و2.4 يوان مع Max Mode؛ كما أن الكوفر بالصوت في 【موصى به】 واجهة الملف الصوتي الشخصي يكلف 1.2 يوان لكل طلب (و2.4 يوان مع max_mode).
• لا ينطبق variety إلا على عائلة suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini)؛ وإرساله مع أي نموذج آخر يعيد 400.
• المؤثرات الصوتية وفصل المسارات و concat و WAV وعمليات التحرير في Studio (crop، حذف مقطع، fade، العكس، تغيير السرعة وما شابه) لا تقبل هذين المعاملين — وإرسالهما صراحةً يعيد 400، حتى لا يُتجاهل أي معامل بصمت.
• قيمة variety عدد صحيح خام من 0 إلى 4؛ أما style_weight و weirdness_constraint فهما عددان عشريان من 0 إلى 1، أي أن المقياسين مختلفان.

حقول الرد الشائعة للأغنية

نقاط نهاية التوليد والكوفر و Extend والفصل والاستعلام تعيد عادةً مصفوفة أغانٍ بهذه الحقول:

أربع خطوات للتكامل (مثال عملي مختصر)

أنجز هذه الخطوات الأربع وستحصل على أغنيتك الأولى؛ وقائمة الحقول الكاملة لكل خطوة موجودة في الصفحة المقابلة ضمن قائمة نقاط النهاية الموصى بها.

# 1) أرسل طلب التوليد: 0.6 يوان ويعيد مقطوعتين
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Mandarin pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) استعلم عن المهمة حتى تصبح الحالة completed (كل 3-5 ثوان فاصل مناسب)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id الذي أعادته الخطوة 1"}'

# 3) احصل على عنوان الوسائط: كل نقاط نهاية القراءة مجانية؛ وتتوفر song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id نفسه", "kind": "song"}'

عند حدوث مشكلة: 401 / 402 / 403 / 429 مشروحة في مرجع الأخطاء؛ والمهلات والخصم المزدوج في قسم "أوقات الانتظار وإعدادات المهلة" أعلاه؛ وتفاصيل كل نقطة نهاية في قائمة نقاط النهاية الموصى بها أدناه.

توصيات

• على التكاملات الجديدة استخدام suno-v6 في كل المسار.
• في نقاط النهاية التي تذكر سعراً افتراضياً، يتبع المبلغ المحصَّل فعلاً إعداد الأسعار الحالي في لوحة الإدارة والنموذج المطلوب.
• نقاط نهاية التوليد تعيد عادةً مهمة أولاً؛ فاقرأ الصوت النهائي عبر /api/music/query.
• القيمة wait_completion=true تحجب التنفيذ حتى الانتهاء وتناسب الاختبار بحجم صغير؛ أما في الإنتاج فالاستعلام الدوري أفضل.
• قد تتأخر نقاط نهاية التوليد كثيراً قبل أن ترد — اضبط مهلة العميل على 300 ثانية أو أكثر، وتذكّر أن "عدم وجود رد" ليس مثل "عدم وجود توليد"؛ راجع "أوقات الانتظار وإعدادات المهلة" أعلاه.
• تعتمد إمكانات الرفع والكوفر و replace و WAV على حسابات المنصة وأذونات مقطع المصدر؛ وعند الفشل اقرأ أولاً message أو error_message المُعاد.

عن هذه الوثائق

أُعيد تنظيم هذه الصفحة حسب الإمكانات التي يعرضها Create UI فعلاً، وعلى التكاملات الجديدة قراءتها أولاً. ولا تزال وثائق API القديمة متاحة في قسم "وثائق API القديمة (المتوافقة)" لمن يريد الاستمرار في استخدامها.