API تولید در حالت سفارشی

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

توضیح نقطه پایانی

حالت سفارشی زمانی مناسب است که متن، سبک و عنوان آماده‌اند و می‌خواهید صدای خواننده، شدت تأثیر سبک و میزان تصادفی‌بودن تولید را کنترل کنید.

نقطه پایانی: POST /api/music/create/custom

صورت‌حساب: پرداختی، فعلاً به‌طور پیش‌فرض 0.6 یوان برای هر فراخوانی. هر فراخوانی معمولاً 2 آهنگ برمی‌گرداند؛ مبلغی که واقعاً کسر می‌شود تابع پیکربندی فعلی قیمت در پنل مدیریت است.

Max Mode / Variety: این نقطه پایانی دو پارامتر اختیاری max_mode و variety (0-4) را پشتیبانی می‌کند. با روشن‌بودن max_mode این فراخوانی با 2 برابر قیمت حساب می‌شود (0.6 → 1.2 یوان برای هر فراخوانی)؛ variety هزینه اضافی ندارد. معنی و روش ارسال آن‌ها در بخش «پارامترهای پیشرفته» در مرور کلی API جدید آمده است.

زمان‌های انتظار و مهلت‌ها (مهم): این نقطه پایانی همزمان است — سفارش تنها زمانی پذیرفته و به تولید سپرده می‌شود که پاسخ برسد. بر پایه اندازه‌گیری، بیشتر درخواست‌ها در 1-3 ثانیه پاسخ می‌دهند، حدود 10% بیش از 30 ثانیه طول می‌کشند و طولانی‌ترین حدود 230 ثانیه است. مهلت سمت کلاینت را 300 ثانیه یا بیشتر بگذارید؛ نبود پاسخ به معنای تولید نشدن نیست، و بلافاصله پس از مهلت دوباره تلاش نکنید (سفارش را تکرار می‌کند و دوباره هزینه می‌گیرد). اگر اتصال قطع شد، بعداً با GET /api/music/songs بررسی کنید. بخش «زمان‌های انتظار و تنظیم مهلت» در مرور کلی API جدید را ببینید.

پارامترهای درخواست

Headers

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

توضیح پارامترهای پیشرفته

جنسیت صدا vocal_gender

• برای صدای مرد m یا male و برای صدای زن f یا female بفرستید.
• سرویس male و female را به‌ترتیب به m و f نرمال می‌کند.
• با instrumental=true هیچ پارامتر جنسیت صدایی به سرویس تولید فرستاده نمی‌شود.

تأثیر سبک style_weight

میزان پایبندی نتیجه به style_tags را کنترل می‌کند. هرچه مقدار بالاتر باشد، نتیجه بیشتر از برچسب‌های سبکی که وارد کرده‌اید پیروی می‌کند.

تصادفی‌بودن weirdness_constraint

میزان تغییر و گرایش آزمایشی نتیجه را کنترل می‌کند. مقدارهای بالاتر معمولاً تنوع بیشتری می‌دهد و مقدارهای پایین‌تر نتیجه‌ای محافظه‌کارانه‌تر.

هر دو پارامتر عددی بین 0.0 و 1.0 هستند و 0 مقدار صریح معتبری است. تنها حذف کامل فیلد به معنای «تعیین‌نشده» است.

هنگام پر کردن توجه کنید که این‌ها کسر اعشاری‌اند، نه عدد صحیح درصدی. مرجع پیشنهادی: 0.0–0.3 محافظه‌کارانه، 0.4–0.6 متعادل، 0.7–1.0 آزمایشی‌تر؛ اگر ترجیح روشنی ندارید از 0.5 استفاده کنید یا آن‌ها را حذف کنید. نمونه: weirdness_constraint: 0.5، هرگز 50 یا 50% ننویسید.

با instrumental=true نتیجه بی‌کلام است، پس متن و جنسیت صدا مانند آهنگ خوانده‌شده عمل نمی‌کنند؛ اگر خواننده لازم دارید false بفرستید یا فیلد را حذف کنید. فیلدهای بولی باید true/false به شکل JSON باشند، نه رشته.

نمونه درخواست پایتون

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nشب بر سطح دریا می‌نشیند\nنسیم غروب از کنار پنجره می‌گذرد',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'نسیم غروب کنار دریا',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

حالت رسید پذیرش (اختیاری)

این نقطه پایانی حالت رسید پذیرش API تولید در حالت ساده را هم پشتیبانی می‌کند: با افزودن "accept_mode": "async" به بدنه (یا هدر X-Accept-Mode: async) نقطه پایانی بی‌درنگ 202 و شماره رسید برمی‌گرداند، تولید در پس‌زمینه ادامه می‌یابد و پیشرفت را با GET /api/music/requests/{request_id} پی می‌گیرید.

مناسب کلاینت‌هایی که نباید اتصال طولانی نگه دارند یا نمی‌خواهند مهلت به‌اشتباه «تولید نشدن» خوانده شود. بدون این پارامتر رفتار دقیقاً مانند قبل است.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "نسیم غروب کنار دریا",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

شکل پاسخ و روش پرس‌وجوی دوره‌ای در بخش «حالت رسید پذیرش» API تولید در حالت ساده آمده است.

اعتبارسنجی پارامترها

این موارد HTTP 400 برمی‌گردانند و message خطا فیلد نامعتبر را نام می‌برد:

• style_weight یا weirdness_constraint عدد نیست.
• مقدار عددی کمتر از 0.0 یا بیشتر از 1.0 است.
• vocal_gender یکی از m، f، male، female نیست.

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

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

پیام خطا به شکل style_tags must not exceed 1000 characters; received 2772 است: واژه نخست نام فیلد متخلف و پایان شمارش اندازه‌گیری‌شده است، پس با دیدن 400 فقط با همین دو عدد کوتاه کنید و لازم نیست فیلد به فیلد آزمون کنید. قواعد کلی در «سقف فیلدهای متنی» مرور کلی API جدید آمده است.

پاسخ

نقطه پایانی معمولاً آرایه‌ای شامل 2 آهنگ برمی‌گرداند. درخواست ناهمزمان معمولاً با وضعیت pending شروع می‌شود؛ song_id را ذخیره کنید و وضعیت نهایی و آدرس صوتی را از API پرس‌وجوی آهنگ بگیرید. فیلدهای آهنگ همانند API تولید در حالت ساده است.

فیلدهای سازگار

اتصال‌های جدید بهتر است همه‌جا snake_case را به کار ببرند. اگر یک درخواست هر دو snake_case و camelCase را داشته باشد، مقدار snake_case اولویت دارد.