API دانلود Free2

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

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

Free2 یک مسیر دانلود پولی جداگانه است: از شناسه آهنگ (یا پیوند آهنگ در suno.com) فایل‌های MP3/WAV/متن ترانه/فراداده را استخراج می‌کند و نشانی‌های دانلود میزبانی‌شده روی پلتفرم را برمی‌گرداند. فقط کلید API را می‌پذیرد، نشست ورود مرورگر را نمی‌پذیرد، و پاسخ هیچ‌گاه منبع پخش رمزگذاری‌شده سونو را در بر نمی‌گیرد.

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

صورت‌حساب: بر پایه تعداد آهنگ‌های موفق محاسبه می‌شود و مقدار پیش‌فرض کنونی ۰.۲ یوان برای هر آهنگ است. انتخاب چند نوع فایل در یک درخواست هزینه اضافی ندارد؛ آهنگ‌هایی که استخراجشان ناموفق بماند هزینه‌ای ندارند. حداکثر ۱۰ آهنگ در هر درخواست (پس از حذف تکراری‌ها)؛ مبلغ واقعی کسرشده تابع تنظیمات قیمت در پنل مدیریت است.

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

احراز هویت

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

دست‌کم یکی از song_id یا song_ids را بفرستید و در files حداقل یک مقدار بدهید.

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

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

پاسخ

{
  "code": 200,
  "message": "success",
  "data": {
    "songs": [
      {
        "song_id": "song_id_1",
        "files": [
          {"type": "mp3", "url": "https://media.suno-api.io/assets/song_id_1-free2-v1-mp3.mp3"}
        ]
      },
      {
        "song_id": "song_id_2",
        "files": [],
        "error": {"code": "song_not_found", "message": "song not found or not owned by the current user"}
      }
    ],
    "requested_songs": 2,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

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

استفاده مجدد از نشانی‌های نهان‌شده (بدون هزینه)

برای آهنگی که پیش‌تر دانلود کرده‌اید، دانلود دوباره نیازی به استخراج تازه ندارد و هزینه‌ای هم ندارد: با POST /api/music/free2/cached نشانی‌های کنونی همان فایل‌هایی را بگیرید که این حساب پیش‌تر دانلود کرده است.

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

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

⚠️ اعتبار نشانی دانلود: ۷ روز — به‌موقع ذخیره کنید. مقدار songs[].files[].url توسط فضای ذخیره‌سازی شیئی پلتفرم ارائه می‌شود و به‌طور پیش‌فرض پس از ۷ روز منقضی می‌شود (فایل‌ها بازیافت می‌شوند و نشانی قدیمی 404 برمی‌گرداند)؛ در همین ۷ روز آن‌ها را در فضای ذخیره‌سازی خودتان ذخیره کنید. پس از انقضا، POST /api/music/free2 را دوباره فراخوانی کنید تا فایل‌ها از نو آماده شوند و نشانی معتبر تازه بگیرید (آن آماده‌سازی مجدد طبق قواعد معمول هزینه دارد؛ /api/music/free2/cached فقط نشانی‌های نهان‌گاهِ همچنان معتبر را برمی‌گرداند).

پارامترهای درخواست: دقیقاً مانند POST /api/music/free2 (هر یک از song_id / song_ids / songs و حداقل یک مقدار در files).

curl -X POST https://www.suno-api.io/api/music/free2/cached \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "song_ids": ["98ca3f1d-…", "a185b3d9-…"], "files": ["mp3"] }'

{
  "success": true,
  "data": {
    "items": [
      { "song_id": "98ca3f1d-…", "type": "mp3", "url": "https://…/assets/98ca3f1d-…-free2-v1-mp3.mp3" }
    ],
    "songs": [
      { "song_id": "98ca3f1d-…", "files": [ { "type": "mp3", "url": "https://…" } ], "missing_files": [] },
      { "song_id": "a185b3d9-…", "files": [], "missing_files": ["mp3"] }
    ],
    "missing": ["a185b3d9-…"]
  }
}

نشانی‌ها فقط برای آهنگ‌هایی برگردانده می‌شوند که پیش‌تر دانلود کرده‌اید؛ آهنگ‌های بدون سابقه دانلود یا آهنگ‌هایی که دارایی آن‌ها بازیافت شده تنها در missing می‌آیند و هیچ نشانی‌ای برایشان برگردانده نمی‌شود.

نکات

• POST /api/music/free2 می‌تواند هر آهنگ عمومی در سونو را استخراج کند (از جمله آهنگ‌هایی که در این پلتفرم نیستند)؛ اگر استخراج آهنگی ناموفق باشد فقط برای همان آهنگ error برمی‌گردد و بقیه آهنگ‌های همان دسته تأثیری نمی‌گیرند. در مقابل، POST /api/music/free2/cached فقط برای آهنگ‌هایی نشانی می‌دهد که این حساب دانلود کرده است.
• نخستین استخراج هر آهنگ فایل‌های میزبانی‌شده را می‌سازد و پس از آن همان‌ها بازاستفاده می‌شوند؛ در files نوع تکراری نفرستید، سرور خودش تکراری‌ها را حذف می‌کند.
• تفاوت با API دانلود و پیش‌نمایش رسانه آهنگ: Free2 پولی است، ارسال مستقیم پیوند suno.com را پشتیبانی می‌کند و جز ترانه، نوع خط زمانی/MIDI ارائه نمی‌دهد.