API سمپل

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

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

سمپلینگ تکّه‌ای از ماده را از یک آهنگ موجود برمی‌دارد و از آن آهنگ تازه‌ای می‌سازد. در حال حاضر حالتی که به مشتریان باز است حالت سمپل chop است.

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

صورت‌حساب: پرداختی و بر پایه مدل درخواستی محاسبه می‌شود؛ مبلغی که واقعاً کسر می‌شود تابع پیکربندی قیمت در پنل مدیریت است.

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 جدید را ببینید.

احراز هویت

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

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

curl -X POST https://www.suno-api.io/api/music/sample \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "source_clip_id": "source_song_id",
    "mode": "chop",
    "start_seconds": 0,
    "end_seconds": 30,
    "style_tags": "funky pop, chopped sample",
    "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 پرس‌وجو کنید.

نکات

• در حال حاضر فقط حالت chop باز است.
• as-is، as_is، asis و blend در حال حاضر کد HTTP 400 برمی‌گردانند و کار تولیدی ارسال نمی‌کنند.
• start_seconds باید 0 یا بیشتر و کمتر از end_seconds باشد.