API کاور از کلیپ منبع

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

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

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

نقطه پایانی: POST /api/music/generate-from-source

صورت‌حساب: پرداختی، فعلاً به‌طور پیش‌فرض 0.6 یوان برای هر فراخوانی. بارگذاری خودِ صدای منبع رایگان است؛ هزینه زمانی گرفته می‌شود که از کلیپ منبع کاور بسازید. مبلغی که واقعاً کسر می‌شود تابع پیکربندی فعلی قیمت در پنل مدیریت است.

Max Mode / Variety: این نقطه پایانی دو پارامتر اختیاری max_mode و variety (0-4) را پشتیبانی می‌کند. با روشن‌بودن max_mode این فراخوانی با 2 برابر قیمت حساب می‌شود (0.6 → 1.2 یوان برای هر فراخوانی)؛ variety هزینه اضافی ندارد. معنی و روش ارسال آن‌ها در بخش «پارامترهای پیشرفته» در مرور کلی API جدید آمده است.

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

روش استفاده توصیه‌شده: این گام 2 «کاور دو مرحله‌ای» است. در گام 1 با API بارگذاری صدای منبع بارگذاری کنید (رایگان) و clip_id را نگه دارید؛ در گام 2 این نقطه پایانی را برای شروع کاور فراخوانی کنید. این‌گونه صدا فقط در گام رایگان ظاهر می‌شود: اگر بارگذاری خراب شد، همان را دوباره امتحان می‌کنید و هزینه‌ای گرفته نمی‌شود، در حالی که بدنه درخواست در گام هزینه‌دار تنها چند صد بایت است، پس تقریباً نمی‌تواند به‌خاطر بریده‌شدن انتقال شکست بخورد. API بارگذاری و سپس کاور در یک مرحله تمام صدا را در بدنه درخواست می‌گذارد، پس به‌محض اینکه صدا از حدود 8 مگابایت بگذرد، در مسیر به‌سادگی بریده می‌شود و unexpected end of JSON input برمی‌گرداند (بخش «فایل‌های بزرگ و درخواست‌های بریده» در آن صفحه را ببینید).

علاوه بر این، همان clip_id را می‌توان برای Extend، Replace Section، جداکردن استم‌ها و دیگر کارهای بعدی بازاستفاده کرد؛ نیازی به بارگذاری دوباره صدا نیست.

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

Headers

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

weirdnessConstraint، styleWeight و audio_weight همگی عددی اعشاری به‌عنوان نسبت از 0.0 تا 1.0 می‌گیرند، نه عدد صحیح درصدی؛ مثلاً 50% را 0.5 بنویسید. مقدار 0 معتبر است و تنها حذف‌کردن فیلد به معنای «مشخص‌نشده» است. audio_weight به metadata.control_sliders.audio_weight در سونو نقشه می‌شود و میزان تکیه نتیجه بر صدای مرجع را کنترل می‌کند؛ تنها وقتی می‌توان آن را فرستاد که درخواست sourceClipId معتبر یا صدای مرجع داشته باشد، پس در تولید معمولی و صرفاً متنی آن را نفرستید. با customMode=true متن تازه را در prompt بنویسید و style و title را هم‌زمان بدهید؛ با customMode=false توضیح ساخت را در prompt بنویسید. instrumental و waitAudio باید از مقادیر منطقی JSON یعنی true/false استفاده کنند.

این نقطه پایانی به‌طور پیش‌فرض ناهمگام پاسخ می‌دهد. تا وقتی status برگشتی pending است، خالی‌بودن audio_url طبیعی است؛ پیش از استفاده از نشانی صدا منتظر پایان کار بمانید. sourceClipId باید شناسه واقعی آهنگ/کلیپ منبع باشد — از task_id، client_request_id یا شناسه جانشین با pending: استفاده نکنید.

sourceClipId چه شناسه‌ای است

sourceClipId شناسه واقعی کلیپ سونو است که به‌عنوان منبع این کاور استفاده می‌شود. شیء آهنگ سمت مشتری در پلتفرم معمولاً این شناسه را song_id می‌نامد، در حالی که پارامترهای درخواست کاور نام sourceClipId را نگه می‌دارند؛ اینجا هر دو به یک شناسه واقعی آهنگ اشاره دارند.

اگر منبع بارگذاری تقویت‌شده است، ابتدا وظیفه بارگذاری تقویت‌شده را بپرسید و صبر کنید تا status به completed برسد، سپس song_id واقعی برگشتی را در sourceClipId بگذارید. توصیه می‌شود audio_url و title همان نتیجه را هم در sourceAudioUrl و sourceTitle بگذارید.

task_id، client_request_id یا شناسه جانشین pending:enhanced-upload:* مربوط به بارگذاری تقویت‌شده را در sourceClipId نگذارید.

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

curl -X POST https://www.suno-api.io/api/music/generate-from-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "sourceClipId": "uploaded_or_existing_clip_id",
    "sourceAudioUrl": "https://example.com/source.mp3",
    "sourceTitle": "عنوان صدای اصلی",
    "prompt": "متن تازه یا جهت ساخت",
    "customMode": true,
    "style": "Mandopop, warm vocal",
    "title": "عنوان کاور",
    "negativeTags": "noise",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false
  }'

پاسخ

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "عنوان کاور",
        "status": "pending"
      }
    ],
    "source_update": {}
  }
}

نکات

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