API دانلود و پیش‌نمایش رسانه آهنگ

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

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

این گروه از نقطه‌های پایانی «گرفتن نشانی رسانه» را از «دانلود واقعی فایل» جدا می‌کند:

• برای گرفتن نشانی‌ای که بتوان مستقیم پخش یا دانلود کرد (مثلاً برای گذاشتن در پخش‌کننده خودتان یا کپی به فضای ذخیره‌سازی شیئی): از POST /api/music/download-url یا همان GET /api/music/download که در پاسخ‌ها آمده استفاده کنید.
• برای اینکه مرورگر خودش فایل را روی دیسک ذخیره کند: از POST /api/music/download-file (یک فایل) یا POST /api/music/download-all (بسته) استفاده کنید.
• اگر آهنگ هنوز در حال ساخت است و می‌خواهید اول گوش کنید: از POST /api/music/generation-stream-url استفاده کنید.

صورت‌حساب: همه رایگان است. دانلود و پیش‌نمایش فقط رسانه‌ای را می‌خوانند که پلتفرم از قبل میزبانی می‌کند؛ سونو را صدا نمی‌زنند و هزینه‌ای برداشت نمی‌شود.

مدل پیشنهادی: suno-v6. مدل‌های suno-v6، suno-v6-wild و suno-v6-mini در دسترس‌اند.

احراز هویت

انواع رسانه پشتیبانی‌شده (kind)

1) دریافت نشانی رسانه

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"}'

{
  "code": 200,
  "message": "success",
  "data": {
    "song_id": "song_id",
    "kind": "song",
    "url": "https://media.suno-api.io/assets/song_id-mp3.mp3",
    "nav_url": "https://media.suno-api.io/assets/song_id-mp3.mp3?...&response-content-disposition=attachment..."
  }
}

url برای پخش یا کپی‌کردن به‌دست خودتان است؛ nav_url هدر Content-Disposition: attachment دارد و برای چسباندن مستقیم در نوار نشانی مرورگر و دانلود مناسب است (زمانی که برخی مرورگرهای موبایل دانلود مبتنی بر blob را پشتیبانی نمی‌کنند).

⚠️ اعتبار نشانی: ۷ روز — به‌موقع فایل را منتقل کنید

url / nav_url به فضای ذخیره‌سازی شیئی پلتفرم اشاره می‌کنند و به‌طور پیش‌فرض پس از ۷ روز منقضی می‌شوند (فایل‌ها بازیافت می‌شوند و نشانی قدیمی 404 برمی‌گرداند). در همین ۷ روز آن‌ها را به فضای ذخیره‌سازی خودتان منتقل کنید.

پس از انقضا نیازی به تولید دوباره آهنگ نیست: کافی است POST /api/music/download-url را دوباره فراخوانی کنید (یا refresh: true بفرستید) تا نشانی‌های معتبر تازه برای آن آهنگ بگیرید. این گروه از نقطه‌های پایانی رایگان است و هزینه‌ای اضافه نمی‌کند.

2) دانلود مستقیم یک فایل

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": "song_id", "kind": "song"}' \
  -o song.mp3

بدنه پاسخ یک جریان فایل است (نه JSON) و Content-Disposition نام فایل را همراه دارد. متن ترانه و متن ترانه با مهر زمانی فقط با همین نقطه پایانی گرفته می‌شود (download-url تنها نشانی رسانه را برمی‌گرداند، نه متن ترانه). فایل .lrc فعلاً فقط برای برخی آهنگ‌ها پشتیبانی می‌شود؛ اگر success:false برگشت، با روش بخش بعدی و API متن ترانه با مهر زمانی خودتان .lrc را بسازید و دوباره تلاش نکنید.

نحوه دریافت متن ترانه با مهر زمانی (.lrc)

دو گام پیشنهاد می‌شود که برای هر آهنگی کار می‌کند:

گام ۱: گرفتن خط زمانی واژه‌به‌واژه (رایگان)

curl -X POST https://www.suno-api.io/api/lyrics/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "suno-v6", "song_id": "song_id"}'

خروجی مستقیماً یک آرایه است (بدون پوشش data)؛ هر عضو این شکل را دارد: {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. word خودش خطوط جدید دارد، پس می‌توانید آن را خط‌به‌خط جدا کنید؛ برای معنی فیلدها، فیلترکردن بخش‌های بی‌کلام و دیگر هشدارها به «فیلدها» و «نکات استفاده» در API متن ترانه با مهر زمانی نگاه کنید.

گام ۲: ساختن .lrc به‌دست خودتان از start_s (قالب زمان [mm:ss.cc])

def to_lrc(segments):
    lines = []
    for seg in segments:
        text = seg["word"].strip()
        if not text:
            continue
        start = max(0.0, float(seg["start_s"]))
        cs = int(start * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

GET /api/music/download?song_id=<id>&kind=lrc هم فایل .lrc ساختهٔ سرور را مستقیم دانلود می‌کند، اما فعلاً فقط برخی آهنگ‌ها پشتیبانی می‌شوند: اگر success:false برگشت، خودتان به روش بالا بسازید — نیازی به تلاش دوباره نیست و بر صورت‌حساب اثری ندارد.

3) دانلود بسته‌ای

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_ids": ["song_id_1", "song_id_2"]}' \
  -o songs.zip

از song_id (یک آهنگ) یا song_ids (دسته‌ای، حداکثر ۵۰ مورد) استفاده کنید. بدنه پاسخ یک جریان ZIP است.

4) نشانی دانلود پایدار

GET /api/music/download?song_id=<id>&kind=<kind> دروازهٔ دانلودی است که مستقیماً در پاسخ‌های آهنگ داده می‌شود. هم کلید API و هم نشست ورود را می‌پذیرد، رفتاری مانند download-file دارد و برای قرار دادن ثابت در کلاینت یا پخش‌کنندهٔ شخص ثالث مناسب است.

5) پیش‌نمایش هنگام تولید

curl -X POST https://www.suno-api.io/api/music/generation-stream-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}'

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "song_id": "song_id_1",
        "url": "https://media.suno-api.io/assets/song_id_1-mp3.mp3",
        "expires_at": 0,
        "content_type": "audio/mpeg",
        "playable_until_completed": false,
        "mode": "mp3",
        "ranges": true
      }
    ]
  }
}

اگر playable_until_completed برابر true باشد، یعنی این نشانی پیش‌نمایش موقت آهنگی است که در حال تولید است؛ پس از کامل‌شدن آهنگ به نشانی دائمی بروید. اگر یک آهنگ ناموفق باشد، آن مورد فیلد error می‌گیرد و بقیهٔ آهنگ‌ها مثل معمول برمی‌گردند.

نکات

• همهٔ نقطه‌های پایانی تنها نشانی رسانه‌های میزبانی‌شده روی پلتفرم را برمی‌گردانند و هرگز منبع رمزگذاری‌شدهٔ سونو یا نشانی امضاشدهٔ موقت را برنمی‌گردانند.
• نشانی‌ها دائمی نیستند؛ اگر می‌خواهید بلندمدت نگه دارید خودتان فایل‌ها را کپی کنید و وقتی فایل اصلی روی دیسک لازم است از download-file استفاده کنید.
• MIDI هر استم نیاز دارد جداسازی آن استم تمام شده باشد، وگرنه خطا برگردانده می‌شود.