API بارگذاری و سپس کاور در یک مرحله

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

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

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

نقطه پایانی: POST /api/music/upload-cover

صورت‌حساب: پرداختی، فعلاً به‌طور پیش‌فرض 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 جدید را ببینید.

وقتی صدا بزرگ است، بهتر است «بارگذاری» و «کاور» را به دو مرحله جدا کنید (توصیه‌شده)

این نقطه پایانی می‌خواهد تمام صدا در بدنه درخواست قرار بگیرد: هرچه صدا بزرگ‌تر، بدنه بزرگ‌تر، و یک لرزش شبکه یا مهلت، انتقال را در میانه قطع می‌کند و پس از آن سرور unexpected end of JSON input برمی‌گرداند (HTTP 400، بدون هزینه).

وقتی صدا از حدود 8 مگابایت می‌گذرد، شبکه ناپایدار است یا همان مواد منبع چند بار استفاده می‌شود، به شکل دو مرحله‌ای بروید:

1. POST /api/music/upload-source نخست صدای منبع را بارگذاری می‌کند — رایگان، هر زمان قابل تکرار — و clip_id می‌دهد؛
2. POST /api/music/generate-from-source با همان clip_id کاور را آغاز می‌کند — بدنه درخواست در مرحله هزینه‌دار فقط حدود 250 بایت است.

API بارگذاری صدای منبع، API کاور از کلیپ منبع و بخش «فایل‌های بزرگ و درخواست‌های بریده» در پایان همین صفحه را ببینید.

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

Headers

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

واحد cover_start_s و cover_end_s ثانیه است و می‌تواند اعشاری باشد؛ زمان آغاز باید کوچک‌تر از زمان پایان باشد و از طول صدای منبع فراتر نرود. اگر هر دو فیلد حذف شوند، تمام صدا استفاده می‌شود. audio_weight به metadata.control_sliders.audio_weight در سونو نقشه می‌شود و میزان تکیه نتیجه بر صدای مرجع را کنترل می‌کند؛ مقدارش 0.0-1.0 است و تنها زمانی می‌توان آن را فرستاد که درخواست صدای مرجع معتبر در file_url یا file_base64 داشته باشد. مقدار 0 معتبر است؛ حذف فیلد یعنی «مشخص‌نشده» و رفتار پیش‌فرض سونو حفظ می‌شود. instrumental و waitAudio باید مقدار منطقی JSON باشند، نه رشته.

نقطه پایانی بارگذاری به‌طور پیش‌فرض ناهمگام پاسخ می‌دهد. تا وقتی clips[].status در پاسخ pending است، خالی‌بودن audio_url طبیعی است و به معنای شکست بارگذاری یا کاور نیست؛ song_id واقعی برگشتی را ذخیره کنید و با نقطه پایانی جست‌وجوی آهنگ تا کامل‌شدن پرس‌وجو کنید و سپس نشانی صدا را بخوانید.

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

curl -X POST https://www.suno-api.io/api/music/upload-cover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "prompt": "متن تازه یا جهت اقتباس",
    "style": "Mandopop, acoustic guitar",
    "title": "نسخه کاور",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

پاسخ

{
  "code": 200,
  "message": "success",
  "data": {
    "upload": {
      "clip_id": "uploaded_clip_id",
      "status": "complete"
    },
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "نسخه کاور",
        "status": "pending"
      }
    ]
  }
}

فایل‌های بزرگ و درخواست‌های بریده

توصیه‌شده: جدا کردن بارگذاری و کاور به دو مرحله

نقطه پایانی یک‌مرحله‌ای (همین یکی) بارگذاری و تولید را در یک مرحله ادغام می‌کند: بدنه بزرگ در همان مرحله واحد قرار دارد، پس با قطع‌شدن معلوم نیست چیزی تولید شده یا هزینه‌ای کسر شده است.

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

400 unexpected end of JSON input یعنی چه

یعنی JSONی که سرور دریافت کرده ناقص است (نه پارامتر اشتباه، نه مشکل دسترسی یا موجودی). دلایل رایج به ترتیب احتمال:

1. بریده‌شدن بدنه بزرگ در میانه انتقال: لایه ورودی هم «چند بایت که کلاینت اعلام کرده» و هم «چند بایت که واقعاً رسیده» را ثبت می‌کند. مورد اندازه‌گیری‌شده: کلاینت 14.17 مگابایت اعلام کرد اما فقط 11.8–12.4 مگابایت رسید و هر سه درخواست حدود 1.6–1.7 ثانیه متوقف شدند؛ تعداد بایت‌های کم‌شده هر بار متفاوت بود، که نشان‌دهنده قطع انتقال است نه سقف ثابت (سرور اندازه بدنه درخواست را محدود نمی‌کند).
2. ناسازگاری Content-Length با بایت‌های واقعاً ارسال‌شده: در Node.js استفاده از .length رشته (تعداد نویسه‌های UTF-16) به‌عنوان طول، وقتی محتوا چینی یا متن چندبایتی دارد اشتباه محاسبه می‌کند.
3. نوشتن بدنه به‌صورت رشته به‌جای Buffer، که بایت‌های نوشته‌شده با اعلام‌شده نمی‌خواند.

هر سه مورد پیش از هزینه‌کردن رخ می‌دهند، پس هزینه‌ای ایجاد نمی‌شود.

چک‌لیست خودبررسی سمت کلاینت

• مقدار Content-Length از Buffer.byteLength(json, 'utf8') (یا Buffer.from(json).length) گرفته می‌شود — هرگز از json.length؛
• بدنه درخواست به‌صورت Buffer نوشته می‌شود، نه رشته؛
• مهلت سوکت / درخواست ≥ 300 ثانیه؛
• وقتی صدا بیش از حدود 8 مگابایت است: از file_url استفاده کنید (بدنه فقط چند صد بایت است)، یا بارگذاری multipart در upload-source، یا مستقیماً شکل دو مرحله‌ای؛
• در درخواست‌های multipart Content-Type را دستی تنظیم نکنید (boundary را کلاینت اضافه می‌کند)؛
• «بایت‌های واقعاً ارسال‌شده» را چاپ کنید و با Content-Length مقایسه کنید؛
• در شکل دو مرحله‌ای، پیش از فرستادن مرحله 2 مطمئن شوید مرحله 1 clip_id و status در وضعیت کامل برگردانده است.

خطاهای رایج

نقاط پایانی مرتبط: API بارگذاری صدای منبع (مرحله 1)، API کاور از کلیپ منبع (مرحله 2).