API افزودن ترک
توضیح نقطه پایانی
افزودن ترک یک ساز یا ترک مشخص را به آهنگ موجود اضافه می‌کند؛ مثلاً درام، بیس، سازهای زهی یا ترک همخوانی.
نقطه پایانی: POST /api/music/add-stem
صورت‌حساب: پرداختی و بر پایه مدل درخواستی محاسبه می‌شود؛ مبلغی که واقعاً کسر می‌شود تابع پیکربندی قیمت در پنل مدیریت است.
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 فعلی قابل دسترسی باشد |
| stem_control_tags | string | بله | - | دستور یک‌خطی افزودن ترک، حداکثر 120 نویسه، مثلاً add Drums |
| lyrics | string | خیر | - | متن آهنگ، در صورتی که باید همراه ترک تولید شود |
| style_tags | string | خیر | - | برچسب‌های سبک |
| song_title | string | خیر | - | عنوان نتیجه |
| negative_tags | string | خیر | - | برچسب‌های سبک حذف‌شده |
| wait_completion | boolean | خیر | false | آیا مدت بیشتری پیش از پاسخ صبر کند |
نمونه درخواست
curl -X POST https://www.suno-api.io/api/music/add-stem \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-v6",
"source_clip_id": "source_song_id",
"stem_control_tags": "add Drums",
"song_title": "درام افزوده‌شده",
"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 پرس‌وجو کنید.
نکات
stem_control_tagsباید متن یک‌خطی و ناتهی باشد؛ نمی‌تواند شامل خط جدید یا تب باشد و حداکثر 120 نویسه است.- افزودن ترک با جداسازی ترک یکی نیست: جداسازی آهنگ را به آواز، موسیقی همراهی یا چند ترک تقسیم می‌کند؛ برای این کار از API جداسازی (آواز و موسیقی همراهی) استفاده کنید.
دریافت کلید API
پس از ثبت‌نام از کنسول یک کلید API بسازید. هر تولید ۰٫۶ یوان هزینه دارد و ۲ قطعه برمی‌گرداند، دانلودها نامحدود است و به شماره تلفن نیازی نیست.
دریافت کلید API بازگشت به مرور کلی