واجهة التوليد بالوضع المخصص

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

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

الوضع المخصص مناسب عندما تكون الكلمات والأسلوب والعنوان جاهزة وتريد التحكم في صوت الغناء وقوة تأثير الأسلوب ودرجة عشوائية التوليد.

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

الفوترة: مدفوع، وحالياً 0.6 يوان افتراضياً لكل طلب. يعيد الطلب عادةً مقطوعتين؛ والمبلغ المخصوم فعلاً يتبع إعداد الأسعار الحالي في لوحة الإدارة.

Max Mode / Variety: تدعم نقطة النهاية هذه المعاملين الاختياريين max_mode و variety (0-4). عند تشغيل max_mode يُحاسَب هذا الطلب بضعف السعر (0.6 → 1.2 يوان لكل طلب)، ولا يضيف variety أي تكلفة. والمعنى وطريقة الإرسال في قسم «المعاملات المتقدمة» من نظرة عامة على الواجهة الجديدة.

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

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

Headers

معاملات جسم الطلب

ملاحظات على المعاملات المتقدمة

جنس الصوت vocal_gender

• أرسل m أو male لصوت رجل، و f أو female لصوت امرأة.
• تُطبّع الخدمة male و female إلى m و f على التوالي.
• عند instrumental=true لا يُرسل معامل جنس الصوت إلى خدمة التوليد.

تأثير الأسلوب style_weight

يتحكم في قوة التزام النتيجة بـ style_tags. فكلما ارتفعت القيمة زاد ميل النتيجة إلى اتباع وسوم الأسلوب التي أدخلتها.

العشوائية weirdness_constraint

يتحكم في مقدار تنوّع النتيجة وطابعها التجريبي. القيم الأعلى تعطي عادةً تنوّعاً أكبر، والأقل نتيجة أكثر تحفظاً.

يقع المعاملان الرقميان بين 0.0 و 1.0، و 0 قيمة صريحة صحيحة. ولا يعني «غير محدد» إلا إغفال الحقل بالكامل.

عند تعبئتهما، لاحظ أنهما كسور عشرية وليسا أعداداً صحيحة بالنسبة المئوية. المرجع المقترح: 0.0–0.3 متحفظ، 0.4–0.6 متوازن، 0.7–1.0 أكثر تجريبية؛ وإن لم يكن لديك تفضيل واضح فاستخدم 0.5 أو أغملهما. مثال: weirdness_constraint: 0.5، ولا تكتب 50 أو 50%.

عند instrumental=true تكون النتيجة موسيقية بلا غناء، لذا لا تعمل الكلمات وجنس الصوت كما في أغنية مغنّاة؛ وإن احتجت غناءً فأرسل false أو أغفل الحقل. ويجب أن تستخدم الحقول المنطقية قيم JSON true/false لا نصوصاً.

مثال الطلب بلغة Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nالليل ينزل على البحر\nنسيم المساء يمر بجانب النافذة',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'نسيم المساء عند البحر',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

وضع إيصال القبول (اختياري)

تدعم هذه النقطة أيضاً وضع إيصال القبول من واجهة التوليد بالوضع المبسّط: عند إضافة "accept_mode": "async" إلى الجسم (أو الترويسة X-Accept-Mode: async) تُعيد النقطة فوراً 202 مع رقم إيصال، ويستمر التوليد في الخلفية، وتتابع التقدم عبر GET /api/music/requests/{request_id}.

مناسب للعملاء الذين لا ينبغي أن يمسكوا اتصالاً طويلاً، أو لا يريدون أن تُقرأ المهلة على أنها «لم يُولَّد شيء». وبدون هذا المعامل يكون السلوك مطابقاً تماماً لما سبق.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "نسيم المساء عند البحر",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

شكل الاستجابة وطريقة الاستعلام الدوري في قسم «وضع إيصال القبول» من واجهة التوليد بالوضع المبسّط.

التحقق من المعاملات

تعيد هذه الحالات HTTP 400، ويسمّي حقل message الحقل غير الصالح:

• style_weight أو weirdness_constraint ليس رقماً.
• قيمة رقمية أقل من 0.0 أو أكبر من 1.0.
• vocal_gender ليس أحد m أو f أو male أو female.

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

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

تأتي رسالة الخطأ على الشكل style_tags must not exceed 1000 characters; received 2772: الكلمة الأولى اسم الحقل المتجاوز، والنهاية العدد المقيس، فعند استلام 400 اختصر حسب هذين الرقمين دون تجربة الحقول واحداً واحداً. والقواعد العامة في «حدود الحقول النصية» بـنظرة عامة على الواجهة الجديدة.

الاستجابة

تُعيد النقطة عادةً مصفوفة تضم مقطوعتين. ويبدأ الطلب غير المتزامن عادةً بحالة pending؛ فاحفظ song_id ثم اقرأ الحالة النهائية وعنوان الصوت عبر واجهة استعلام الأغاني. وحقول الأغنية هي نفسها في واجهة التوليد بالوضع المبسّط.

الحقول المتوافقة

على التكاملات الجديدة استخدام snake_case في كل مكان. وإن حمل الطلب نفسه snake_case و camelCase معاً، تُعطى الأولوية لقيمة snake_case.