مرور کلی مستندات Suno API

به‌روزرسانی 2026-09-18 · تیم Suno-API

با ثبت‌نام از طریق ایمیل می‌توانید یک کلید API بسازید. هر تولید 0.6 یوان هزینه دارد، 2 قطعه برمی‌گرداند و شامل دانلود MP3/WAV، کاور، Extend، جداسازی استم و استنساخ صدا می‌شود. آدرس پایه: https://www.suno-api.io.

این صفحه مدل‌های موجود در حال حاضر، همه نقاط پایانی تولید و ویرایش، روش صورت‌حساب و ترتیب پیشنهادی مطالعه را فهرست می‌کند. اگر برای نخستین بار در حال اتصال هستید، آن را از بالا به پایین بخوانید؛ بخش عیب‌یابی 401/403/429 هم همین‌جاست.

پاسخ‌های کوتاه

چطور کلید API بگیرم؟ با ایمیل ثبت‌نام کنید، کنسول را باز کنید، به مدیریت توکن بروید و یک توکن بسازید. به شماره تلفن و کارت بانکی نیازی نیست.

هر فراخوانی چقدر هزینه دارد؟ هر تولید 0.6 یوان هزینه دارد و 2 قطعه برمی‌گرداند. پرس‌وجوی وضعیت، WAV، متن ترانه با برچسب زمانی و پیشنهاد پرامپت رایگان است.

کدام مدل‌ها پشتیبانی می‌شوند؟ suno-v6 (پیش‌فرض)، suno-v6-wild و suno-v6-mini. مدل‌های استاندارد تولید v5.5 و قدیمی‌تر بازنشسته شده‌اند؛ کارهای موجود تحت تأثیر قرار نمی‌گیرند.

آدرس پایه چیست؟ https://www.suno-api.io همراه با هدر Authorization: Bearer YOUR_API_KEY.

مدل‌های موجود در حال حاضر

مدل‌های مشتریان برای تولید استاندارد آهنگ عبارت‌اند از suno-v6، suno-v6-wild و suno-v6-mini. اگر model را حذف کنید، سیستم از suno-v6 استفاده می‌کند.

مدل‌های استاندارد suno-v2، suno-v3، suno-v3-5، suno-v4، suno-v4-5، suno-v4-5-all، suno-v4-5-plus، suno-v5 و suno-v5-5 بازنشسته شده‌اند. ممکن است کارهای قدیمی هنوز این نام‌ها را نشان دهند؛ این داده تاریخی است و نشانه آن نیست که مدل برای درخواست‌های جدید قابل استفاده است. جداسازی استم استثناست — به API جداسازی استم (جداسازی خواننده/موسیقی) مراجعه کنید.

احراز هویت

همه نقاط پایانی عمومی که با کلید API کار می‌کنند از یک مجموعه هدر استفاده می‌کنند:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

آدرس پایه:

https://www.suno-api.io

قواعد کلی پارامترها

• مقدار number در بدنه باید عدد JSON باشد، نه رشته درصدی. شدت ۵۰٪ را 0.5 بنویسید و هرگز 50 یا 50% ننویسید.
• مقدار boolean باید true یا false باشد. از 0 یا 1 به‌عنوان جایگزین استفاده نکنید.
• فیلدهایی که «خیر» علامت خورده‌اند را می‌توانید کاملاً حذف کنید. اگر مطمئن نیستید یک پارامتر چه می‌کند، آن را خالی بگذارید تا سرویس از رفتار پیش‌فرض خود استفاده کند؛ به‌جای «ارسال‌نشده» رشته خالی یا null یا 0 نفرستید، چون 0 برای بعضی فیلدهای عددی مقدار معتبری است.
• نام فیلدها به املا حساس است. هر صفحه نقطه پایانی نام پیشنهادی و نام‌های جایگزین سازگار را فهرست می‌کند؛ دقیقاً همان‌طور که جدول پارامترها نشان می‌دهد بفرستید. جایی که مستندات می‌گوید هم snake_case و هم camelCase پذیرفته می‌شود، هر دو را همزمان نفرستید.
• هر فیلد مدت‌زمانی که به _s یا Seconds ختم می‌شود بر حسب ثانیه است و اعشار را می‌پذیرد. برچسب‌های زمانی Unix جداگانه توضیح داده شده‌اند، از جمله اینکه بر حسب ثانیه یا میلی‌ثانیه هستند.
• شناسه‌ای که با pending: شروع می‌شود جانگهدار پلتفرم است، نه song_id واقعی. آن را فقط جایی به کار ببرید که نقطه پایانی صریحاً پشتیبانی از جانگهدار را مستند کرده باشد؛ در غیر این صورت منتظر song_id واقعی بمانید.

سقف فیلدهای متنی

عبور از سقف متن مستقیماً HTTP 400 برمی‌گرداند: چیزی تولید نمی‌شود، مبلغی از پیش کسر نمی‌شود و رکورد کاری ساخته نمی‌شود. شمارش بر پایه نویسه یونیکد است (یک نویسه چینی 1 حساب می‌شود) و فاصله‌های ابتدا و انتها هم شمرده می‌شوند.

فیلد message نام فیلد متخلف و طول اندازه‌گیری‌شده را می‌گوید، پس همین دو عدد برای کوتاه‌کردن کافی است:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

اعمال می‌شود بر: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

یک استثنا: فیلد description در POST /api/music/sounds به 100 نویسه محدود است، چون مسیر افکت‌های صوتی از سقف کوتاه‌تر پلتفرم استفاده می‌کند.

تولید ناهمزمان و آدرس‌های صوتی

نقاط پایانی تولید موسیقی به‌طور پیش‌فرض ناهمزمان کار می‌کنند. وقتی پاسخ اول مقدار status برابر pending یا submitted یا processing دارد، خالی‌بودن audio_url یا video_url یا cover_url طبیعی است و به معنی شکست کار نیست. song_id واقعی (یا client_request_id که نقطه پایانی برگردانده) را ذخیره کنید و نقطه پایانی پرس‌وجوی متناظر را فراخوانی کنید؛ آدرس صوتی را فقط پس از تکمیل وضعیت بخوانید و دانلود کنید.

⚠️ آدرس‌های صوتی پس از 7 روز منقضی می‌شوند — فایل‌هایتان را به‌موقع منتقل کنید

audio_url، wav_url، video_url و آدرس‌هایی که نقاط پایانی دانلود برمی‌گردانند از انبار شیئی پلتفرم سرو می‌شوند و به‌طور پیش‌فرض پس از 7 روز منقضی می‌شوند (فایل‌ها بازیافت می‌شوند؛ آدرس قدیمی 404 می‌دهد یا دانلود نمی‌شود).

• در همان 7 روز، فایل‌ها را به انبار خودتان منتقل کنید (انبار شیئی خودتان، CDN یا دیسک سرور). آدرس‌های ما را لینک بلندمدت در نظر نگیرید.
• آدرس منقضی‌شده نیازی به تولید دوباره آهنگ ندارد و هزینه اضافی هم نمی‌سازد: API پرس‌وجوی آهنگ (یا API دانلود رسانه) را دوباره فراخوانی کنید تا آدرس تازه و معتبر همان آهنگ را بگیرید.

زمان‌های انتظار و تنظیم مهلت

نقاط پایانی تولید همزمان هستند: سفارش فقط زمانی پذیرفته و برای تولید به پلتفرم سپرده می‌شود که پاسخ برسد. پیش از آن، سرویس باید حسابی را زمان‌بندی کند و بررسی امنیتی اجباری را بگذراند و هیچ پاسخ میانی وجود ندارد — هیچ نقطه پایانی دیگری هم این سفارش را نمی‌بیند. پس تنها شاهد مطمئن برای اینکه «چیزی تولید شده»، خودِ پاسخ است، نه آنچه در حین انتظار می‌بینید.

زمان‌های انتظار اندازه‌گیری‌شده (خانواده /api/music/create در محیط تولید، 2026-09-18 تا 2026-09-20)

• حدود ۱۰٪ درخواست‌ها بیش از ۳۰ ثانیه طول می‌کشند و حدود ۱٪ بین ۱ تا ۲ دقیقه. درخواست کند معمولاً یعنی همان درخواست باید نخست از بررسی امنیتی بگذرد.
• فیلدهای درخواست، شکل پاسخ، کدهای خطا و صورت‌حساب تغییری نکرده‌اند، پس اتصال‌های موجود فقط باید مهلت سمت کلاینت را بالا ببرند — بدون هیچ تغییر کد دیگری.

الزامات اتصال

1. مهلت سمت کلاینت را ۳۰۰ ثانیه یا بیشتر بگذارید. کلاینتی که پیش‌فرض ۳۰ یا ۶۰ یا ۱۲۰ ثانیه دارد، در میانه انتظار اتصال را می‌بندد.
2. نبود پاسخ به معنی تولید نشدن نیست. در مهلت‌تمام‌شدن یا قطع اتصال، ممکن است سفارش پذیرفته شده باشد و در حال تولید باشد.
3. بی‌درنگ پس از پایان مهلت دوباره تلاش نکنید: ارسال تکراری سفارش دوم می‌سازد و دوباره هزینه کسر می‌کند.
4. اگر اتصال قطع شد، کمی بعد آهنگ‌هایتان را با GET /api/music/songs (تازه‌ترین اول) فهرست کنید — سفارش‌های پذیرفته‌شده به‌طور عادی ظاهر می‌شوند. تنها وقتی دوباره بفرستید که مطمئن شده‌اید سفارش واقعاً وجود ندارد.
5. هنگام گزارش مشکل، هدر پاسخ X-Oneapi-Request-Id را هم بفرستید تا همان درخواست مستقیم قابل ردیابی باشد.

نمی‌خواهید اتصال طولانی نگه دارید؟ از حالت رسید پذیرش استفاده کنید. POST /api/music/create و POST /api/music/create/custom یک رسید پذیرش اختیاری پشتیبانی می‌کنند: "accept_mode": "async" را به بدنه اضافه کنید (یا هدر X-Accept-Mode: async) و نقطه پایانی بی‌درنگ 202 را همراه شماره رسید برمی‌گرداند در حالی که تولید در پس‌زمینه ادامه دارد؛ با GET /api/music/requests/{request_id} پیشرفت را بپایید. کلاینتی که فقط چند ده ثانیه مهلت دارد دیگر «بی‌پاسخی» را به‌اشتباه «تولید نشدن» نمی‌خواند و با تلاش دوباره دوبار هزینه نمی‌پردازد. بخش «حالت رسید پذیرش» را در API تولید حالت ساده ببینید.

برای مرجع: python requests از timeout=300 استفاده می‌کند، urllib از urlopen(..., timeout=300)، Node از req.setTimeout(300000) و curl از --max-time 300.

فهرست نقاط پایانی پیشنهادی

مسیرهای /api/voice/clone/* و /api/music/generate-with-voice زنجیره استنساخ صدای نسل اول هستند و برای اتصال‌های جدید توصیه نمی‌شوند؛ در عوض از 【توصیه‌شده】 API پروفایل صدا استفاده کنید.

پارامترهای پیشرفته: Max Mode و Variety

نقاط پایانی تولید این دو پارامتر اختیاری را پشتیبانی می‌کنند (حذف آن‌ها رفتار و قیمت قبلی را حفظ می‌کند):

این دو پارامتر پشتیبانی می‌شوند در: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• قیمت دوبرابر در عمل: نقطه پایانی‌ای که 0.6 یوان برای هر فراخوانی است با max_mode به 1.2 یوان می‌رسد؛ تولید با صدای انتخابی 1.2 یوان برای هر فراخوانی و با Max Mode برابر 2.4 یوان است؛ کاور با صدا در 【توصیه‌شده】 API پروفایل صدا هم 1.2 یوان برای هر فراخوانی است (و با max_mode برابر 2.4 یوان).
• variety فقط روی خانواده suno-v6 (suno-v6، suno-v6-wild، suno-v6-mini) اثر دارد؛ فرستادن آن با هر مدل دیگری 400 برمی‌گرداند.
• افکت‌های صوتی، جداسازی استم، concat، WAV و عملیات ویرایش Studio (crop، حذف بخش، fade، معکوس‌سازی، تغییر سرعت و مانند آن) این دو پارامتر را نمی‌پذیرند — ارسال صریح آن‌ها 400 برمی‌گرداند، تا هیچ پارامتری بی‌صدا نادیده گرفته نشود.
• variety عدد صحیح خام 0 تا 4 است؛ در حالی که style_weight و weirdness_constraint اعشار از 0 تا 1 هستند، پس مقیاس‌ها متفاوت‌اند.

فیلدهای رایج پاسخ آهنگ

نقاط پایانی تولید، کاور، extend، جداسازی و پرس‌وجو معمولاً آرایه‌ای از آهنگ‌ها با این فیلدها برمی‌گردانند:

چهار گام برای اتصال (نمونه کمینه و عملی)

همین چهار گام را انجام دهید تا نخستین آهنگتان را بگیرید؛ فهرست کامل فیلدهای هر گام در صفحه متناظر آن در فهرست نقاط پایانی پیشنهادی آمده است.

# 1) ارسال درخواست تولید: 0.6 یوان و 2 قطعه
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Mandarin pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) تا رسیدن وضعیت به completed پرس‌وجو کنید (فاصله 3-5 ثانیه مناسب است)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id بازگشتی از گام 1"}'

# 3) گرفتن آدرس رسانه: نقاط پایانی خواندن همه رایگان‌اند؛ song / wav / video / cover / midi موجود است
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "همان song_id", "kind": "song"}'

وقتی مشکلی پیش آمد: 401 / 402 / 403 / 429 در مرجع خطاها توضیح داده شده‌اند؛ مهلت‌ها و کسر دوباره هزینه در بخش «زمان‌های انتظار و تنظیم مهلت» بالا؛ و جزئیات هر نقطه پایانی در فهرست نقاط پایانی پیشنهادی در پایین.

توصیه‌ها

• اتصال‌های جدید بهتر است در همه مسیر از suno-v6 استفاده کنند.
• در نقاط پایانی‌ای که قیمت پیش‌فرض می‌دهند، مبلغی که واقعاً کسر می‌شود از پیکربندی قیمت فعلی پنل مدیریت و مدل درخواستی تبعیت می‌کند.
• نقاط پایانی تولید معمولاً ابتدا یک کار برمی‌گردانند؛ صدای نهایی را از /api/music/query بخوانید.
• wait_completion=true تا پایان کار منتظر می‌ماند و برای آزمون با حجم کم مناسب است؛ در محیط تولید پرس‌وجوی دوره‌ای ترجیح دارد.
• ممکن است پاسخ نقاط پایانی تولید بسیار طول بکشد — مهلت سمت کلاینت را 300 ثانیه یا بیشتر بگذارید، و به یاد داشته باشید «نبود پاسخ» با «تولید نشدن» یکی نیست؛ بخش «زمان‌های انتظار و تنظیم مهلت» بالا را ببینید.
• قابلیت‌های بارگذاری، کاور، replace و WAV به حساب‌های پلتفرم و مجوزهای کلیپ منبع وابسته‌اند؛ هنگام شکست، ابتدا message یا error_message بازگشتی را بخوانید.

درباره این مستندات

این صفحه بر پایه قابلیت‌هایی که Create UI در واقع نشان می‌دهد بازآرایی شده است و اتصال‌های جدید بهتر است نخست آن را بخوانند. مستندات قدیمی API هم در بخش «مستندات قدیمی API (سازگار)» برای کسانی که می‌خواهند به استفاده از آن ادامه دهند در دسترس است.