واجهة توليد المؤثرات الصوتية

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

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

توليد المؤثرات الصوتية يُنتج بضع ثوانٍ من الصوت، وليس أغنية. وهو مناسب للأصوات القصيرة مثل الرعد أو قطرات المطر أو صوت اصطدام، وكذلك لمؤثرات الانتقال وأصوات الجو وحلقات الطبول؛ ومعظمها أقل من 5 ثوانٍ وأطولها نحو 20 ثانية. ويدعم الوضعين المرة الواحدة والحلقة.

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

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

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

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

Headers

المعامل	النوع	مطلوب	ملاحظات
Authorization	string	نعم	Bearer YOUR_API_KEY
Content-Type	string	نعم	application/json

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

المعامل	النوع	مطلوب	القيمة الافتراضية	ملاحظات
model	string	لا	suno-v6	اسم النموذج للعميل: `suno-v6` أو `suno-v6-wild` أو `suno-v6-mini`
description	string	نعم	-	صِف الصوت الذي تريده؛ العبارات الإنجليزية القصيرة هي الأكثر ثباتاً، مثل `cinematic whoosh transition, bright impact`
title	string	لا	-	العنوان؛ وإذا لم يُرسل يمكن توليده من الوصف
type	string	لا	one_shot	النوع: `one_shot` (مرة واحدة) أو `loop` (حلقة)
loop	boolean	لا	false	هل يُشغَّل في حلقة؛ ويعادل ضبط `type` على `loop`
bpm	number	لا	-	BPM؛ يجب أن يكون رقماً أكبر من 0. القيمة غير الصحيحة تُعيد 400 (`invalid_sound_bpm`) ولا تُتجاهل بصمت
key	string	لا	-	المقام، بصيغة اسم النغمة (C-B) + `#`/`b` اختياري + `Major`/`Minor` اختياري، مثل `C Major` أو `C#m` أو `Bb`؛ والقيمة الفارغة أو `any` تعني بلا قيد. القيمة غير الصحيحة تُعيد 400 (`invalid_sound_key`)

مثال الطلب

curl -X POST https://www.suno-api.io/api/music/sounds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "description": "cinematic whoosh transition, bright impact",
    "title": "cinematic whoosh",
    "type": "one_shot",
    "loop": false,
    "bpm": 120,
    "key": "C"
  }'

الاستجابة

يُعاد مصفوفة أغانٍ؛ والحقول هي نفس حقول الاستجابة العامة للأغنية في نظرة عامة على الواجهة الجديدة.

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

احصل على مفتاح API

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

احصل على مفتاح API العودة إلى النظرة العامة