API افزودن موسیقی همراهی
توضیح نقطه پایانی
افزودن موسیقی همراهی یک آهنگ موجود را دوباره تنظیم می‌کند، ساز اضافه می‌کند یا ساختار همراهی تازه می‌سازد.
نقطه پایانی: POST /api/music/add-instrumental
صورت‌حساب: پرداختی و بر پایه مدل درخواستی محاسبه می‌شود؛ مبلغی که واقعاً کسر می‌شود تابع پیکربندی قیمت در پنل مدیریت است.
Max Mode / Variety: این نقطه پایانی پارامترهای اختیاری max_mode و variety (0-4) را پشتیبانی می‌کند. با روشن بودن
max_mode این فراخوانی با قیمت دوبرابر محاسبه می‌شود؛ variety هزینه‌ای اضافه ندارد. معنی آن‌ها و روش ارسال
در بخش «پارامترهای پیشرفته» مرور کلی API جدید آمده است.
مدل پیشنهادی: suno-v6. می‌توان از suno-v6، suno-v6-wild و suno-v6-mini استفاده کرد.
زمان‌های انتظار و مهلت‌ها (مهم): این نقطه پایانی همزمان است — سفارش تنها زمانی پذیرفته و به تولید سپرده می‌شود که پاسخ برسد. بر پایه اندازه‌گیری، بیشتر درخواست‌ها در 1-3 ثانیه پاسخ می‌دهند، حدود 10% بیش از 30 ثانیه طول می‌کشند و طولانی‌ترین حدود 230 ثانیه است. مهلت سمت کلاینت را 300 ثانیه یا بیشتر بگذارید؛ نبود پاسخ به معنای تولید نشدن نیست، و بلافاصله پس از مهلت دوباره تلاش نکنید (سفارش را تکرار می‌کند و دوباره هزینه می‌گیرد). اگر اتصال قطع شد، بعداً با
GET /api/music/songsبررسی کنید. بخش «زمان‌های انتظار و تنظیم مهلت» در مرور کلی API جدید را ببینید.
احراز هویت
| پارامتر | نوع | الزامی | یادداشت |
|---|---|---|---|
| Authorization | string | بله | Bearer YOUR_API_KEY |
| Content-Type | string | بله | application/json |
پارامترهای درخواست
| پارامتر | نوع | الزامی | پیش‌فرض | یادداشت |
|---|---|---|---|---|
| model | string | بله | - | نام مدل برای مشتری: suno-v6، suno-v6-wild یا suno-v6-mini |
| source_clip_id | string | بله | - | song_id واقعی آهنگ منبع؛ باید کامل شده و برای کلید API فعلی قابل دسترسی باشد |
| lyrics | string | خیر | - | متن تازه یا جهت خلاقانه |
| style_tags | string | خیر | - | برچسب‌های سبک |
| song_title | string | خیر | - | عنوان نتیجه |
| negative_tags | string | خیر | - | برچسب‌های سبک حذف‌شده |
| audio_weight | number | خیر | 1 | وزن تأثیر صدای مرجع، در بازه 0.0-1.0؛ مقدار پیش‌فرض 1 یعنی حفظ آهنگ اصلی به‌عنوان مرجع تا حد امکان |
| duration | integer | خیر | - | مدت دلخواه بر حسب ثانیه، بازه 1-480. کمینه عملی پلتفرم حدود 30 ثانیه است: با درخواست 10 ثانیه، اندازه‌گیری همچنان 29.96 / 29.76 ثانیه بود |
| wait_completion | boolean | خیر | false | آیا مدت بیشتری پیش از پاسخ صبر کند؛ استفاده ناهمزمان توصیه می‌شود |
نمونه درخواست
curl -X POST https://www.suno-api.io/api/music/add-instrumental \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-v6",
"source_clip_id": "source_song_id",
"lyrics": "",
"style_tags": "cinematic, strings, acoustic guitar",
"song_title": "نسخه با همراهی تقویت‌شده",
"audio_weight": 1,
"wait_completion": false
}'
پاسخ
{
"code": 200,
"message": "success",
"data": {
"clips": [
{
"song_id": "result_song_id",
"song_title": "نسخه با همراهی تقویت‌شده",
"status": "pending"
},
{
"song_id": "result_song_id_2",
"song_title": "نسخه با همراهی تقویت‌شده",
"status": "pending"
}
]
}
}
یک فراخوانی 2 نتیجه برمی‌گرداند (به‌عنوان 2 آهنگ حساب می‌شود)؛ نمونه دو مورد را نشان می‌دهد. ملاک طول آرایه clips است و حلقه با تعداد ثابت ننویسید. مقدار clips[].song_id را ذخیره کنید و با API پرس‌وجوی آهنگ و تاریخچه تا رسیدن به completed پرس‌وجو کنید. سپس می‌توانید با audio_url پخش یا دانلود کنید؛ API ساخت و دریافت WAV و دیگر نقاط دانلود را ببینید.
نکات
source_clip_idباید شناسه واقعی، کامل‌شده و در دسترس کلید API فعلی باشد؛ شناسه جانشینpending:پذیرفته نمی‌شود.- افزودن موسیقی همراهی کاور نیست؛ برای کاور از API کاور از کلیپ منبع استفاده کنید.
- برای افزودن ساز یا ترک مشخص به آهنگ موجود، از API افزودن ترک استفاده کنید.
دریافت کلید API
پس از ثبت‌نام از کنسول یک کلید API بسازید. هر تولید ۰٫۶ یوان هزینه دارد و ۲ قطعه برمی‌گرداند، دانلودها نامحدود است و به شماره تلفن نیازی نیست.
دریافت کلید API بازگشت به مرور کلی