API جداسازی (آواز و موسیقی همراهی)

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

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

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

1. اگر صدای منبع آهنگی نیست که روی این پلتفرم ساخته شده، نخست API بارگذاری صدای منبع را فراخوانی کنید.
2. برای ارسال کار جداسازی، POST /api/music/separate را فراخوانی کنید.
3. نتیجه را با API پرس‌وجوی آهنگ و تاریخچه پرس‌وجو کنید.
4. فایل صوتی هر نتیجه جداسازی را با نقطه‌های پایانی دانلود دریافت کنید.

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

صورت‌حساب: پرداختی. stem_mode=two فعلاً به‌طور پیش‌فرض 0.6 یوان برای هر فراخوانی؛ و stem_mode=twelve یک جداسازی چندترکی است و فعلاً 3.0 یوان برای هر فراخوانی. مبلغی که واقعاً کسر می‌شود تابع پیکربندی قیمت در پنل مدیریت است.

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

احراز هویت

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

توضیح stem_mode

توضیح جداسازی

جداسازی یک قابلیت ثابت و مستقل است و نیازی به وارد کردن یا انتخاب مدل تولید آهنگ ندارد. مشتری فقط آهنگ منبع و stem_mode را می‌فرستد و سرور بر پایه حالت پردازش می‌کند.

اعداد از کجا می‌آیند: هر ارسال ۲ نسخه تولید می‌کند (دو نتیجه از یک مواد)، پس تعداد = ۲ × تعداد ترک‌های آن حالت: برای two چهار و برای twelve بیست‌وچهار. همیشه طول واقعی آرایه clips در پاسخ را معیار بگیرید و حلقه‌ای با عدد ثابت ننویسید (ممکن است برخی ترک‌ها ناموفق شوند و ترک‌های موفق طبق معمول برگردند).

هر حالت چه ترک‌هایی برمی‌گرداند

۱۲ ترک حالت twelve (نام‌ها را پلتفرم ثابت می‌دهد؛ ترتیب ممکن است تغییر کند):

حالت two دو ترک (Vocals) و (Instrumental) را برمی‌گرداند که هرکدام ۲ نسخه دارند. نام ترک‌های two و twelve نام‌های ثابت هستند (نام آهنگ منبع را ندارند)، پس انتظار نداشته باشید از نام ترک بفهمید مربوط به کدام آهنگ است.

نام ترک را نمی‌توان کلید یکتا گرفت. در دو نسخه، ترک‌هایی با نام یکسان ظاهر می‌شوند (مثلاً دو (Vocals) و دو (Strings))، و یک جداسازی ترک‌های زیادی برمی‌گرداند. همیشه song_id را شناسه بگیرید و song_title را فقط برای نمایش به کار ببرید؛ از اندیس‌های آرایه هم استفاده نکنید (ترتیب ممکن است تغییر کند).

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

جداسازی آواز / موسیقی همراهی (stem_mode: "two")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "two",
    "source_audio_url": "https://example.com/source.mp3",
    "source_file_name": "source.mp3",
    "source_title": "Source Song"
  }'

جداسازی چندترکی (stem_mode: "twelve")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "twelve",
    "source_audio_url": "https://example.com/source.mp3"
  }'

پاسخ

در صورت موفقیت معمولاً آرایه‌ای از نتایج جداسازی بازگردانده می‌شود. هر نتیجه یک کلیپ آهنگ مستقل است و باید تا رسیدن status به وضعیت کامل، پرس‌وجو ادامه یابد.

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "stem_clip_id_1",
        "song_title": "(Vocals)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      },
      {
        "song_id": "stem_clip_id_2",
        "song_title": "(Instrumental)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      }
    ]
  }
}

در بالا فقط ۲ مورد از ۴ مورد حالت two نشان داده شده است؛ در واقع ۴ مورد برمی‌گردد (۲ نسخه × {(Vocals), (Instrumental)})؛ و حالت twelve بیست‌وچهار مورد برمی‌گرداند. تعداد واقعی همان طول آرایه clips است.

مشتری معمولاً فقط باید clips[].song_id را ذخیره کند؛ پرس‌وجو و دانلود بعدی حول همین شناسه‌ها می‌چرخد.

نکات

• نتایج جداسازی در تاریخچه GET /api/music/songs ظاهر نمی‌شوند (آن فهرست فقط آهنگ‌های تولیدشده معمولی را برمی‌گرداند). پس از ارسال موفق، فوراً clips[].song_id را ذخیره کنید، وگرنه بعداً راهی برای یافتنشان نیست.
• هر ترک یک اثر مستقل است: هر ترک song_id خودش را دارد و باید جداگانه تا کامل شدن پرس‌وجو و جداگانه دانلود شود.
• صورت‌حساب به تعداد موارد ربطی ندارد: به ازای هر فراخوانی محاسبه می‌شود (two 0.6 یوان برای هر فراخوانی، twelve 3.0 یوان برای هر فراخوانی) و ۴ یا ۲۴ مورد قیمت یکسانی دارند.
• دانلود: با song_id همان ترک از POST /api/music/download-url / download-file (رایگان) استفاده کنید، یا مستقیم از audio_url در نتیجه پرس‌وجو؛ برای MIDI به API دریافت MIDI مراجعه کنید.
• دو بار ارسال نکنید: جداسازی یک نقطه پایانی همزمان است؛ پس از پایان مهلت ابتدا با پرس‌وجوی آهنگ بررسی کنید و بلافاصله دوباره تلاش نکنید (سفارش تکرار می‌شود و دوباره هزینه کسر می‌گردد).
• ترک‌هایی که دیگر لازم ندارید را با API حذف استم‌ها پنهان کنید.

پرس‌وجوی نتایج جداسازی

پس از ارسال موفق، با clips[].song_id و فراخوانی POST /api/music/query نتایج را پرس‌وجو کنید.

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": "stem_clip_id_1,stem_clip_id_2"
  }'

نمونه پرس‌وجوی کامل‌شده:

[
  {
    "song_id": "stem_clip_id_1",
    "song_title": "(Vocals)",
    "status": "complete",
    "audio_url": "https://...",
    "cover_url": "https://...",
    "duration": 180.5,
    "generation_type": "separate",
    "stem_from_id": "source_clip_id"
  }
]

دانلود فایل‌های ترک

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

نقطه پایانی: POST /api/music/download-file

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1",
    "kind": "audio"
  }' \
  --output stem.mp3

مقادیر پشتیبانی‌شده kind:

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

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1"
  }' \
  --output stem-resources.zip

توضیح وضعیت‌ها

خطاهای رایج

نکات سازگاری

مستندات قدیمی از مثال‌های شیء تکی مانند success/task_id/vocals_url/instrumental_url استفاده می‌کرد. جداسازی کنونی بر پایه آرایه آهنگ‌های clips[] است: هر نتیجه جداسازی song_id مستقل خودش را دارد و پرس‌وجو و دانلود بعدی حول همین song_id می‌چرخد.

نقاط پایانی مرتبط

• اگر فقط می‌خواهید آواز و موسیقی همراهی را جدا کنید و لازم نیست حالت انتخاب کنید، از API حذف آواز استفاده کنید؛ این شکل سریع دوترکی همین نقطه پایانی است و فعلاً رایگان است.
• ترک‌های جداسازی که دیگر لازم ندارید را با API حذف استم‌ها پنهان کنید (حذف نرم، بدون هزینه).
• برای MIDI یک ترک به API دریافت MIDI و برای صدا، جلد و دیگر رسانه‌ها به API دانلود و پیش‌نمایش رسانه آهنگ مراجعه کنید.