API پرس‌وجوی آهنگ و تاریخچه

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

این صفحه سه نقطه پایانی رایگان پرس‌وجو را پوشش می‌دهد:

اگر روی نقطه پایانی تولید از حالت رسید پذیرش (accept_mode=async) استفاده کرده‌اید، چیزی که در دست دارید شماره رسید است، نه شناسه آهنگ. پیشرفت را با GET /api/music/requests/{request_id} پیگیری کنید و پس از دریافت song_id واقعی به نقاط پایانی این صفحه برگردید. بخش «حالت رسید پذیرش» را در API تولید در حالت ساده ببینید.

احراز هویت و دامنه داده

هر سه نقطه پایانی با یک کلید API احراز هویت می‌شوند:

Authorization: Bearer YOUR_API_KEY

تاریخچه آهنگ‌ها بر پایه user_id مالک کلید API جدا می‌شود. چند کلید ساخته‌شده زیر یک حساب اصلی می‌توانند تاریخچه همان حساب را بخوانند، اما نه آهنگ‌های کاربر دیگر یا حساب سایت فرعی دیگر.

نقاط پایانی تاریخچه فقط آهنگ‌های واقعاً تولیدشده را برمی‌گردانند. موارد زیر مستثنا هستند:

• رکوردهای جانگهدار تولید که با pending: شروع می‌شوند؛
• بارگذاری صدای منبع و رکوردهای بارگذاری تقویت‌شده؛
• نتایج فرعی مانند جداسازی خواننده/موسیقی و استم‌ها؛
• آهنگ‌های کاربران دیگر یا حساب‌های سایت فرعی.

1. پرس‌وجوی وضعیت تولید

وضعیت فعلی و نتیجه نهایی یک یا چند شناسه آهنگ را جست‌وجو می‌کند.

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

صورت‌حساب: رایگان.

Headers

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

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

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

نمونه پاسخ

[
  {
    "song_id": "clip_id_1",
    "song_title": "عنوان آهنگ",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "متن ترانه",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

نکات سازگاری

ممکن است مستندات قدیمی song_ids را آرایه نشان دهند. امروزه رشته جدا شده با کاما توصیه می‌شود، که با روش واقعی فراخوانی این نقطه پایانی مطابقت دارد.

song_ids باید شناسه آهنگ واقعی داشته باشد. شناسه جانگهدار که با pending: شروع می‌شود song_id نهایی نیست و اینجا کار نمی‌کند؛ پرس‌وجوی تنها شناسه‌های جانگهدار ممکن است آرایه خالی [] برگرداند.

مقدار model، model_version یا model_name پلتفرم در پاسخ ممکن است مقادیر تاریخی را نگه دارد. کارهای جدید باید از suno-v6، suno-v6-wild یا suno-v6-mini استفاده کنند؛ از suno-v2 تا suno-v5-5 بازنشسته شده‌اند و دیدن این نام‌ها در تاریخچه به معنای امکان ارسال آن مدل نیست.

تا زمانی که کار در وضعیت pending، submitted یا processing است، audio_url، video_url و cover_url ممکن است خالی باشند — این برای کار ناتمام طبیعی است. صرفاً از خالی‌بودن آدرس نتیجه شکست نگیرید؛ به status تکیه کنید و وقتی وضعیت کامل شد دوباره پرس‌وجو کنید. تنها وقتی وضعیت کامل است و آدرس‌ها هنوز خالی‌اند، بهتر است با ذکر song_id با پشتیبانی تماس بگیرید.

⚠️ آدرس‌های صوتی 7 روز زنده‌اند — فایل‌هایتان را به‌موقع منتقل کنید

audio_url، video_url (و دیگر آدرس‌های رسانه مانند WAV) که اینجا برگردانده می‌شوند از انبار شیئی پلتفرم سرو می‌شوند و به‌طور پیش‌فرض پس از 7 روز منقضی می‌شوند: فایل‌ها بازیافت می‌شوند و آدرس قدیمی 404 می‌دهد.

• در همان 7 روز فایل‌ها را به انبار خودتان منتقل کنید؛ این آدرس را لینک بلندمدت ندانید.
• آدرس منقضی‌شده نیازی به تولید دوباره آهنگ ندارد و دوباره هزینه نمی‌گیرد: این نقطه پایانی (POST /api/music/query) را دوباره فراخوانی کنید تا آدرس تازه و معتبر آن آهنگ را بگیرید.

2. پرس‌وجوی تاریخچه آهنگ‌های حساب

آهنگ‌هایی را فهرست می‌کند که حساب اصلی مالک کلید API فعلی ساخته است. مناسب برای ساخت فهرست آهنگ، انتخاب‌گر یا صفحه تاریخچه خودتان.

نقطه پایانی: GET /api/music/songs

صورت‌حساب: رایگان.

پارامترهای پرس‌وجو

نتایج بر اساس created_at و شناسه داخلی رکورد به‌صورت نزولی مرتب می‌شوند، بنابراین ترتیب صفحه‌بندی پایدار می‌ماند.

روش پیدا کردن ارسالی که مهلتش تمام شده: نقاط پایانی تولید پیش از پذیرش هیچ پاسخ میانی نمی‌دهند. اگر کلاینت شما هنگام ارسال به مهلت خورد یا اتصال قطع شد، ممکن است آن سفارش پذیرفته شده و در حال تولید باشد. نگاهی به این نقطه پایانی بیندازید (تازه‌ترین اول): آهنگ‌های پذیرفته‌شده به‌طور عادی در فهرست ظاهر می‌شوند. تنها پس از اطمینان از نبودن آن دوباره ارسال کنید تا دوبار هزینه نپردازید. بخش «زمان‌های انتظار و تنظیم مهلت» را در مرور کلی API جدید ببینید.

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

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

نمونه پاسخ

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "شهر در شب",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

فیلدهای پاسخ

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

3. پرس‌وجوی پارامترهای تولید

پرامپت، سبک، مدل و آهنگ منبعی را که پلتفرم هنگام تولید ذخیره کرده جست‌وجو می‌کند.

نقطه پایانی: GET /api/music/songs/:song_id

صورت‌حساب: رایگان.

فقط آهنگ‌های حساب اصلی مالک کلید API فعلی خوانده می‌شوند. آهنگ‌های کاربران دیگر یا حساب‌های سایت فرعی به‌طور یکسان «آهنگ یافت نشد» تلقی می‌شوند.

پارامتر مسیر

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

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

نمونه پاسخ

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "شهر در شب",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "خیابان‌های شهر پس از باران، متنی درباره دیدار دوباره",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "شهر در شب",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

فیلدهای parameters

فیلد prompt_view (نمایش پرامپت، افزوده‌شده در 2026-09-28)

prompt_view ساختاری نرمال‌شده و مخصوص «نمایش پرامپت» است: داده‌ها را بر پایه نوع تولید در بخش‌های ثابت سازمان می‌دهد، بنابراین کلاینت دیگر لازم نیست تصمیم بگیرد کدام فیلد را نشان دهد. این فیلد صرفاً افزودنی است — فیلدهای قدیمی (parameters، parameter_retention) نام و معنای خود را حفظ می‌کنند و کلاینت‌هایی که فیلد جدید را تجزیه نمی‌کنند هیچ تأثیری نمی‌بینند.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "حالت پیشرفته",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "ساعت چهار بامداد#701f37", "title_base": "ساعت چهار بامداد", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "…", "user_text_kind": "lyrics",
    "user_style": "الکترونیک گوچائو، بیس عمیق، سینت رترو",
    "style_tags": "الکترونیک گوچائو، بیس عمیق، سینت رترو",
    "style_source": "user", "lyrics": "…",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

فیلدهایی که ممکن است در extended ظاهر شوند: vocal_gender، style_weight، audio_weight، weirdness_constraint، variety، lyrics_mode، custom_mode و گروه افکت‌های صوتی sound_type / sound_bpm / sound_key / sound_loop. مقادیر خالی هرگز برگردانده نمی‌شوند.

سه قاعده نمایش (به‌جای حدس‌زدن از این‌ها پیروی کنید):

1. خاستگاه سبک را تفکیک کنید: وقتی style_source=suno_derived است، آن را به‌شکل «سبک (استخراج‌شده توسط Suno از توضیح شما)» نشان دهید و هرگز به‌شکل «سبک شما» ننویسید؛
2. پرامپت‌های داخلی هرگز ظاهر نمی‌شوند: انواع کاور صوتی فقط 【الزامات سبک】/【الزامات کاور】 را که کاربر نوشته برمی‌گردانند؛ ساختار ثابتی که ما برای مدل می‌سازیم در هیچ فیلدی ظاهر نمی‌شود (داده‌های تاریخی هم پاک‌سازی شده‌اند)؛
3. پارامترهای ذخیره‌نشده را حدس نزنید: اگر در extended نیست، آن زمان ثبت نشده — علت را با retention توضیح دهید.

نکات حفظ پارامترها

parameter_retention برای جدا کردن «ارسال صریح مقدار خالی» از «ذخیره‌نشدن تاریخی آن فیلد» است:

• core_parameters_available: آیا رکورد اصلی کار وجود دارد؛ در جزئیات معتبر معمولاً true؛
• extended_parameters_available: آیا رکورد کار موسیقی توسعه‌یافته مرتبط پیدا شده؛
• sources: این پاسخ از کدام جدول‌های داده آمده؛
• unavailable_fields: فیلدهایی که از داده‌های تاریخی قابل بازیابی مطمئن نیستند؛ این فیلدها در parameters مقدار null می‌گیرند.

آهنگ‌های تاریخی معمولی عموماً پرامپت، سبک، عنوان فعلی، مدل، نوع تولید و آهنگ منبع را ذخیره کرده‌اند، اما همه پارامترهای پیشرفته را جدا ذخیره نکرده‌اند. پلتفرم هرگز مقادیر ناموجود را از generation_type حدس نمی‌زند.

برخی کارهای موسیقی توسعه‌یافته، پرامپت اصلی، سبک، عنوان، مدل و همچنین custom_mode، negative_tags، vocal_gender، style_weight و weirdness_constraint را ذخیره کرده‌اند. حتی با وجود رکورد توسعه‌یافته، ممکن است instrumental، lyrics_mode و wait_audio قابل بازیابی نباشند.

عنوان آهنگ‌ها بعداً توسط کاربر قابل تغییر است. وقتی کار تاریخی معمولی عنوان اصلی جداگانه‌ای ذخیره نکرده، ممکن است parameters.title همان عنوان فعلی باشد؛ و وقتی رکورد کار توسعه‌یافته وجود دارد، عنوان تولید اصلی ذخیره‌شده در آن اولویت می‌گیرد.

یافت نشد یا بدون دسترسی

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

{
  "success": false,
  "message": "song not found"
}

این خطای کسب‌وکار اکنون با HTTP 200 برگردانده می‌شود، پس نتیجه را از فیلد success قضاوت کنید. کلید API ناموجود، نامعتبر، منقضی یا غیرفعال HTTP 401 برمی‌گرداند.

نکات امنیتی

نقاط پایانی تاریخچه و جزئیات هرگز این موارد را برنمی‌گردانند:

• کلیدهای API یا شناسه توکن؛
• فیلدهای سهمیه، صورت‌حساب یا بازپرداخت؛
• اطلاعات حساب یا پاسخ خام؛
• کلیدهای داخلی انبار شیئی؛
• خطاهای مدیر و خطاهای منابع داخلی.