API افزودن آواز
توضیح نقطه پایانی
افزودن آواز بخش خواندن را روی یک آهنگ موجود یا یک منبع بی‌کلام می‌سازد، بازنویسی می‌کند یا کامل می‌کند.
نقطه پایانی: POST /api/music/add-vocal
صورت‌حساب: پرداختی و بر پایه مدل درخواستی محاسبه می‌شود؛ مبلغی که واقعاً کسر می‌شود تابع پیکربندی قیمت در پنل مدیریت است.
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 | خیر | - | برچسب‌های سبک حذف‌شده |
| instrumental | boolean | خیر | false | آیا نتیجه بی‌کلام است؛ در حالت افزودن آواز معمولاً false می‌ماند |
| wait_completion | boolean | خیر | false | آیا مدت بیشتری پیش از پاسخ صبر کند |
نمونه درخواست
curl -X POST https://www.suno-api.io/api/music/add-vocal \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-v6",
"source_clip_id": "source_song_id",
"lyrics": "[Verse]\nشب بیرون پنجره فرود می‌آید\n[Chorus]\nما به سوی نور می‌رویم",
"style_tags": "warm male vocal, mandopop, intimate",
"song_title": "نسخه با آواز تقویت‌شده",
"instrumental": false,
"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 پرس‌وجو کنید.
نکات
- افزودن آواز یعنی «ساختن یا بازنویسی آواز روی آهنگ منبع»؛ با ترجیح
vocal_genderیکسان نیست. - برای استفاده از صدای کلون‌شده از 【توصیه‌شده】 API پروفایل صدا استفاده کنید؛ API کلون صدا و ساخت با صدای تعیین‌شده (مسیر قدیمی) برای یکپارچه‌سازی‌های تازه توصیه نمی‌شود.
دریافت کلید API
پس از ثبت‌نام از کنسول یک کلید API بسازید. هر تولید ۰٫۶ یوان هزینه دارد و ۲ قطعه برمی‌گرداند، دانلودها نامحدود است و به شماره تلفن نیازی نیست.
دریافت کلید API بازگشت به مرور کلی