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

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

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

Speech يحوّل نص خطاب أو وصفاً من سطر واحد إلى صوت «كلام/خطاب»، مع موسيقى خلفية اختيارية. يناسب الخطابات وكلمات التحية والسرد ونصوص التعليق الصوتي والمحتوى الصوتي وما شابهها.

تنبيه: هذه الواجهة تُنتج صوت كلام، لا أغنية مُغنّاة (لا لحن ولا غناء). إذا احتجت الغناء فاستخدم واجهة التوليد بالوضع المبسّط أو واجهة التوليد بالوضع المخصص.

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

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

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

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

ملاءمة المحتوى: تتحقق المنصة من النص من حيث حقوق النشر وسياسة المحتوى. وإذا حُكم بأنه يتضمن مواد محمية (مثل الاقتباس من كلمات أغنية لشخص آخر أو نص عمل مشهور حرفياً)، فشل هذا الطلب وأُعيد المبلغ كاملاً تلقائياً. انتقل إلى صياغتك الخاصة، أو حوّل الاقتباس إلى إعادة صياغة، ثم أعد المحاولة.

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

Headers

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

هذه الواجهة لا تدعم duration: تمريره يعيد HTTP 400، ولا يتم تجاهله بصمت. وتُحدَّد مدة الخطاب بطول محتوى script.

أمثلة الطلب

أصغر طلب (النص فقط)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "صباح الخير للجميع! حديثي اليوم عن حسن استغلال وقتنا والمضي قدماً."
  }'

طلب كامل (مع تحديد النبرة والجنس وإيقاف الموسيقى الخلفية)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

مثال بلغة Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'مساء الخير أيها الزملاء. سأستعرض تقدم هذا الأسبوع.',
        'tone': 'هادئ وواضح، تقرير اجتماع',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # عادةً عنصران
for item in items:
    print(item['song_id'], item['status'])

شرح المعاملات

script (الخطاب، مطلوب)

• الصق المحتوى الذي تريد قوله؛ ويمكنك أيضاً كتابة وصف واحد وترك النموذج يكتب الخطاب (مثل «كلمة تحفيزية في استراحة المباراة لفريق متأخر بعشرين نقطة، من همس خفيض إلى هدير بأقصى الصوت»).
• الأسطر الجديدة والفقرات وتوجيهات المسرح مثل [وقفة] يمكن كتابتها مباشرة، وسيتبعها النموذج قدر الإمكان.
• الحد 3000 حرف (يُحسب كحرف Unicode، والحرف الصيني يُحسب 1)؛ وتجاوزه يعيد 400 دون خصم.

tone (النبرة والمكان، اختياري)

يصف كيف يُقال الكلام، لا ما يُقال. ويُستحسن تضمين أربعة أنواع من المعلومات: النبرة، السرعة/الإيقاع، المشاعر، والمكان.

حيوي وقوي، السرعة من بطيء إلى سريع، وقفات واضحة؛ قاعة المدرسة، أمام جميع المعلمين والطلاب
دافئ وناعم، سرعة هادئة؛ حفل زفاف
رصين ومتزن، منتظم وواضح؛ تقرير لمجلس الإدارة

الحد 1000 حرف. وعند عدم تمريره يقدّره النموذج من محتوى script.

gender / vocal_gender (جنس المتحدث، اختياري)

• للصوت الرجالي مرّر m أو male، وللنسائي f أو female؛ ويوحّدها الخادم إلى m / f.
• كلا اسمَي الحقل يعملان، ويكفي أحدهما: gender هو الشكل الموصى به في هذه الواجهة؛ وإن كنت تستخدم الوضع المخصص بالفعل فيمكنك الاستمرار بـ vocal_gender.
• عدم التمرير يعني «غير محدّد»، والنموذج يقرر.

backing_music (الموسيقى الخلفية، اختياري)

• القيمة الافتراضية true (مع موسيقى خلفية)، مثل الإعداد الافتراضي في نسخة ويب من Suno.
• وfalse يعطي خطاباً بالصوت فقط، وهو مناسب إذا أردت لاحقاً إضافة موسيقاك أو تعليقك الصوتي.
• يجب أن يكون قيمة منطقية بصيغة JSON true / false؛ وتُقبل النصوص "true" و"1"، لكن يُفضّل القيم المنطقية.

model (النموذج، اختياري)

النماذج الثلاثة الموجّهة للعميل متاحة بالسعر نفسه (0.6 يوان لكل طلب). ويُولَّد الخطاب بواسطة عائلة Suno v6؛ وعند عدم تمريره يُعامَل بوصفه suno-v6. وإذا لم يكن لديك تفضيل واضح فعادةً لا حاجة لتمرير هذا الحقل.

التحقق من المعاملات وحدود النصوص

الحالات التالية تعيد HTTP 400، وكلها تُمنع قبل الخصم فلا تنتج أي تكلفة:

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

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

تكون رسالة الخطأ على الشكل script must not exceed 3000 characters; received 4120: الكلمة الأولى هي اسم الحقل المتجاوز، والنهاية هي العدد الفعلي، لذا عند تلقي 400 يمكنك الاقتصاص مباشرةً بهذين الرقمين.

الاستجابة

الاستجابة مصفوفة أغانٍ مطابقة تماماً لواجهات التوليد الأخرى (عادةً عنصران)؛ احفظ song_id ثم استخدم واجهة استعلام الأغاني والسجل لمعرفة الحالة النهائية وعنوان الصوت:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "حسن استغلال الوقت",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

فشل التوليد والاسترداد

عند فشل التوليد تُعاد تكلفة ذلك الطلب كاملةً وتلقائياً؛ ولا حاجة للتواصل مع الدعم. ويمكن رؤية السبب في الاستجابة أو في error_message لدى واجهة استعلام الأغاني والسجل.

والسبب الأكثر شيوعاً هو اعتبار المحتوى متضمناً مواد محمية بحقوق النشر، مثل:

Your lyrics contain copyrighted material. Please change it and try again.

في هذه الحالة استبدل النص بصياغتك الخاصة (أو حوّل الاقتباس إلى إعادة صياغة) ثم أرسله من جديد.

أسئلة شائعة

س: لماذا تكون النتيجة «كلاماً» لا غناءً؟ ج: هذه واجهة الخطابات، ومخرجاتها صوت كلام. وللغناء استخدم واجهات التوليد أو الوضع المخصص.

س: لماذا يعيد عنصرين في كل مرة؟ ج: كما في واجهات التوليد الأخرى على المنصة، التوليد الواحد يُنتج مرشحين اثنين؛ استعلم عنهما منفصلين حسب song_id واحتفظ بما يعجبك.

س: كيف أتحكم في المدة؟ ج: تُحددها طول script؛ وهذه الواجهة لا تقبل معامل duration.

س: هل يمكنني تحديد صوت (مثل صوتي المستنسخ)؟ ج: الإصدار الحالي لا يدعم ذلك. الخطاب يستخدم مجموعة أصوات خطاب ثابتة، ويمكن اختيار رجالي أو نسائي عبر gender؛ وإن احتجت صوتك الخاص فاستخدم القدرة ذات الصلة في واجهة إنشاء ملف صوتي شخصي (موصى به).

س: ماذا يحدث إذا لم أمرر tone؟ ج: يقدّر النموذج النبرة والإيقاع من محتوى script. ولإعادة إنتاج أسلوب معيّن بثبات، اكتب النبرة والسرعة والمكان في tone.

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

في عمليات الربط الجديدة استخدم snake_case بشكل موحّد. أما الحقول الأخرى (script وtone وsong_title وbacking_music) فلا تملك أسماء بديلة بصيغة camelCase.

الخطوات التالية

بعد الحصول على song_id:

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