واجهة توليد الكلمات

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

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

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

نقطة النهاية: POST /api/lyrics/generate

الفوترة: مجاني ضمن الحصة (10 طلبات في الدقيقة و300 في اليوم لكل مستخدم على الأكثر)؛ وبعد تجاوز الحصة المجانية تُحتسب 0.1 يوان لكل طلب.

كشف التجاوز: عند تجاوز الحصة المجانية يظل الطلب يعمل بشكل طبيعي، وتحتوي ترويسات الاستجابة على X-Suno-Helper-Free: false و X-Suno-Helper-Over-Limit: minute (أو day)، ويمكن للعميل بناءً على ذلك تنبيه المستخدم بأن هذه المرة محسوبة.

النموذج الموصى به: suno-v6. ويتوفر suno-v6 و suno-v6-wild و suno-v6-mini.

المصادقة

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

يقبل instruction أيضاً الحقلين القديمين theme و prompt. والقيمة الافتراضية لـ metadata.lyrics_model هي default، ولـ metadata.enable_thinking هي false.

التحكم باللغة

لا تحتوي هذه الواجهة على حقل طلب language مستقل. لغة الكلمات يحددها محتوى instruction، ولا يمكن لـ style سوى أداء دور مساعد.

للحصول على كلمات بالصينية، اذكر اللغة الهدف صراحةً في instruction، مثل:

{
  "model": "suno-v6",
  "instruction": "请用中文写歌词，主题是夏夜海边重逢",
  "style": "Mandopop, 中文流行"
}

ويمكنك أيضاً كتابة "Write the lyrics in Chinese about ...". وللحصول على كلمات بالإنجليزية اكتب "请用英文写歌词" أو "Write the lyrics in English". وإذا أرسلت موضوعاً بالإنجليزية فقط دون تحديد اللغة الهدف فقد تكون النتيجة بالإنجليزية.

مثال الطلب

curl -X POST https://www.suno-api.io/api/lyrics/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "instruction": "كلمات بالعربية عن موسم التخرج والبداية من جديد",
    "style": "pop rock, صادق, لازمة سهلة الحفظ",
    "title": "البداية من جديد",
    "metadata": {
      "lyrics_model": "default",
      "enable_thinking": false
    }
  }'

الاستجابة

{
  "code": 200,
  "message": "success",
  "data": {
    "lyrics": "[Verse]\nالريح تعبر الساحة\nنلوّح مودّعين للأمس",
    "edited_lyrics": "[Verse]\nالريح تعبر الساحة\nنلوّح مودّعين للأمس",
    "lyrics_id": "lyrics_id",
    "lyrics_request_id": "lyrics_request_id"
  }
}

edited_lyrics هي الكلمات الكاملة التي يجب إدخالها في مربع الكلمات. أما lyrics_id و lyrics_request_id فهما للتتبّع وقد يكونان فارغين حسب ما تُعيده الواجهة؛ لا تعاملهما كمعرّفات أغانٍ.

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

• الحقلان القديمان theme و prompt ما زالا يعملان ويُحوَّلان إلى instruction.
• سلسلة واجهات "مشروع الكلمات / كاتب الكلمات" متوقفة: إذا أردت الاحتفاظ بالنتائج المولّدة فاحفظ edited_lyrics التي تُعيدها الواجهة بنفسك.