API دریافت MIDI

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

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

نقطه پایانی MIDI ترک‌هایی را که stem دارند به یک فایل MIDI استاندارد تبدیل می‌کند، برای تنظیم، کار خلاقانه بعدی یا وارد کردن در DAW.

Suno نشانی دانلود فایل MIDI ارائه نمی‌دهد؛ فقط داده‌های نُت هر ترک (زیروبمی، زمان شروع و پایان، شدت) را می‌دهد. این نقطه پایانی آن داده‌ها را به فایل MIDI استاندارد (SMF format 1) تبدیل و مستقیماً برمی‌گرداند، بنابراین چیزی که می‌گیرید همیشه یک فایل .mid واقعی است که DAW باز می‌کند.

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

این صفحه نمونه اختصاصی MIDI است. توضیح کامل خانواده دانلود (نشانی رسانه، فایل تک، بسته‌بندی، پیش‌نمایش هنگام تولید) در API دانلود و پیش‌نمایش رسانه آهنگ آمده است.

صورت‌حساب: رایگان. این نقطه پایانی داده‌های نُت stem‌های موجود را می‌خواند و اعتبار کم نمی‌کند.

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

Headers

پارامتر	نوع	الزامی	یادداشت
Authorization	string	بله	Bearer YOUR_API_KEY
Content-Type	string	بله	application/json

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

پارامتر	نوع	الزامی	پیش‌فرض	یادداشت
song_id	string	بله	-	شناسه یک ترک پس از جداسازی (هر clip id که `/api/music/separate` برمی‌گرداند)
kind	string	بله	-	ثابت روی `midi`

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

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",
    "kind": "midi"
  }' \
  --output track.mid

پاسخ

بدنه پاسخ محتوای دودویی فایل MIDI است، نه JSON.

سرآیند پاسخ	مقدار
Content-Type	`audio/midi`
Content-Disposition	`attachment; filename="<عنوان آهنگ>.mid"`

گرفتن نشانی دانلود

اگر اول نشانی را می‌خواهید و بعد دانلود (مثلاً برای بسته‌بندی چند فایل)، ابتدا این را فراخوانی کنید:

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":"stem_clip_id","kind":"midi"}'

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "stem_clip_id",
    "kind": "midi",
    "url": "https://www.suno-api.io/api/music/download?song_id=stem_clip_id&kind=midi"
  }
}

آن نشانی هم به سرآیند Authorization نیاز دارد؛ بدون کلید API کد 401 برگردانده می‌شود.

درباره فایل MIDI

مورد	مقدار	یادداشت
قالب فایل	SMF format 1	1 ترک Tempo + 1 ترک برای هر ساز
دقت زمان	480 PPQ	480 تیک در هر ضرب
تمپو	120 BPM	Suno فقط ثانیه می‌دهد و BPM نمی‌دهد، بنابراین برای نوشتن تایم‌لاین از تمپوی ثابت استفاده می‌شود
تایم‌لاین	`1 ثانیه = 960 تیک`	یک‌به‌یک با ثانیه‌هایی که پلتفرم برمی‌گرداند منطبق است؛ در DAW در صورت نیاز تمپو را تغییر دهید
شدت	0–127	پلتفرم مقادیر اعشاری 0–1 می‌دهد؛ این نقطه پایانی آن‌ها را با ×127 تبدیل کرده است
درام	کانال MIDI 10	ترک‌هایی که پلتفرم به‌عنوان درام علامت می‌زند خودکار روی کانال سازهای کوبه‌ای قرار می‌گیرند

نکات

فقط برای ترک‌هایی که stem دارند معتبر است: song_id باید شناسه ترکی باشد که /api/music/separate برمی‌گرداند، نه شناسه آهنگ اصلی.
نداشتن نُت در stem نتیجه عادی است: برخی ترک‌ها (مثلاً FX) نُت قابل تبدیل ندارند؛ در این حالت به‌جای خطا یک فایل MIDI معتبر بدون نُت برگردانده می‌شود.
MIDI فقط اطلاعات نُت را دارد: صدا، پن و افکت‌ها در MIDI نیستند؛ تیمبر را خودتان در DAW تنظیم کنید.
هر ترک را جداگانه درخواست کنید: یک درخواست فایل .mid یک ترک را برمی‌گرداند؛ برای چند ترک هر یک را جداگانه فراخوانی کنید یا از دانلود بسته‌های Create UI استفاده کنید.

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

دریافت کلید API

پس از ثبت‌نام از کنسول یک کلید API بسازید. هر تولید ۰٫۶ یوان هزینه دارد و ۲ قطعه برمی‌گرداند، دانلودها نامحدود است و به شماره تلفن نیازی نیست.

دریافت کلید API بازگشت به مرور کلی