API بارگذاری تقویت‌شده

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

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

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

نقطه پایانی ارسال: POST /api/music/enhanced-upload

پرس‌وجوی یک کار: GET /api/music/enhanced-upload/:id

لغو کار: POST /api/music/enhanced-upload/:id/cancel

پرس‌وجوی فهرست: GET /api/music/enhanced-upload

صورت‌حساب: 10 یوان برای هر فراخوانی که به‌صورت پیش‌پرداخت با قیمت ثابت suno-enhanced-upload کسر می‌شود. اگر کار ناموفق شود یا در مرحله مجاز لغو شود، مبلغ کسرشده به‌طور خودکار برگشت داده می‌شود. مبلغی که واقعاً کسر می‌شود تابع پیکربندی قیمت در پنل مدیریت است.

جریان فراخوانی

1. برای بارگذاری فایل صوتی، POST /api/music/enhanced-upload را فراخوانی کنید.
2. مقدار task_id برگشتی را ذخیره کنید.
3. برای دیدن پیشرفت و نتیجه، GET /api/music/enhanced-upload/:id را فراخوانی کنید.
4. وقتی سونو رندر نهایی را تمام کرد، سرویس با حساب سونوی مرتبط با همان کار، نقطه پایانی دانلود مجاز Studio را فراخوانی می‌کند و MP3 را در سرویس رسانه CN2 می‌نویسد.
5. کار تنها زمانی completed می‌شود که دارایی CN2 آماده باشد؛ در آن هنگام نشانی صدای CDN از audio_url در پاسخ خوانده می‌شود.

/api/forbidden نشانی جانشینی است که ممکن است در فراداده Suno Studio دیده شود؛ منبع قابل‌پخش یا قابل‌دانلود نیست. هرگز به مشتری برگردانده نمی‌شود و مبنای اتمام کار قرار نمی‌گیرد. اگر رندر تمام شده باشد اما CN2 هنوز آماده‌سازی کند، نقطه پایانی همچنان processing برمی‌گرداند و audio_url نمی‌دهد؛ کلاینت باید پرس‌وجو را ادامه دهد و نشانی خالی را شکست تلقی نکند.

ارسال بارگذاری تقویت‌شده

Headers

پارامترهای فرم

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

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

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

پاسخ

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

پرس‌وجوی یک کار

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

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

نمونه پاسخ در حال پردازش

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

نمونه پاسخ پس از اتمام

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

لغو کار

لغو تنها زمانی ممکن است که هم کار و هم گردش‌کار بک‌اند هنوز در مرحله queued باشند. پس از ورود کار به leasing، running، processing یا پس از اتمام، لغو ممکن نیست.

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

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

پاسخ

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

اگر کار از قبل پردازش را آغاز کرده باشد، نقطه پایانی این را برمی‌گرداند:

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

پرس‌وجوی فهرست کارها

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

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

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

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

پاسخ

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

توضیح فیلدهای پاسخ

نکات

• این نقطه پایانی فعلاً تنها بارگذاری فایل multipart را پشتیبانی می‌کند؛ file_url و file_base64 در قالب JSON پشتیبانی نمی‌شوند.
• حجم فایل بارگذاری‌شده حداکثر ۸۰ مگابایت است.
• نقطه پایانی ارسال ناهمگام است: پاسخ queued یعنی کار در صف قرار گرفته، نه اینکه صدا آماده است.
• لغو تنها برای کارهایی است که پردازششان آغاز نشده؛ پس از آغاز پردازش، گردش‌کار حساب پلتفرم قطع نمی‌شود.
• کلیدهای API واقعی را در کد کلاینت افشا نکنید.

شروع کاور پس از اتمام بارگذاری تقویت‌شده

پس از اتمام بارگذاری تقویت‌شده می‌توانید نتیجه را به‌عنوان کلیپ منبع به کار ببرید و POST /api/music/generate-from-source را برای شروع کاور فراخوانی کنید.

توجه: کاور یک نقطه پایانی همزمان است — سفارش تنها با رسیدن پاسخ پذیرفته می‌شود و بر پایه اندازه‌گیری ممکن است تا حدود ۲۳۰ ثانیه طول بکشد. مهلت سمت کلاینت را ۳۰۰ ثانیه یا بیشتر بگذارید و بلافاصله پس از مهلت دوباره تلاش نکنید. بخش «زمان‌های انتظار و تنظیم مهلت» در مرور کلی API جدید را ببینید.

نخست GET /api/music/enhanced-upload/:id را تا زمانی پرس‌وجو کنید که task.status برابر completed شود. در آن هنگام:

• task.song_id شناسه واقعی آهنگ و همان sourceClipId موردنیاز نقطه پایانی کاور است؛
• توصیه می‌شود task.audio_url را هم به‌عنوان sourceAudioUrl بفرستید تا سرور حالت تفاوت کلیپ منبع با حساب اجراکننده را مدیریت کند؛
• task.task_id تنها شناسه کار بارگذاری تقویت‌شده است و نمی‌تواند sourceClipId باشد؛
• pending:enhanced-upload:* شناسه جانشین مرحله پردازش است و برای کاور قابل استفاده نیست.

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

بقیه پارامترها (متن، سبک، عنوان، مدل) را طبق API کاور از کلیپ منبع پر کنید. پس از آنکه نقطه پایانی کاور clips[].song_id تازه را برگرداند، با POST /api/music/query وضعیت تولید و صدای نهایی را بپرسید.