API بارگذاری صدای منبع

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

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

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

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

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

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

توصیه‌هایی برای بارگذاری فایل‌های بزرگ

پس از پایان بارگذاری، همیشه تأیید کنید که status در پاسخ در حالت کامل است و clip_id را ذخیره کنید و سپس به گام 2 بروید؛ بارگذاری ناموفق هزینه‌ای ندارد و کار تولیدی ایجاد نمی‌کند — فقط دوباره تلاش کنید.

پیش از آپلود، file_url را بررسی کنید

سرور پلتفرم خودش file_url را با HTTP دانلود می‌کند، نه مرورگر شما. بازشدن URL در مرورگر ثابت نمی‌کند که سرور تولید نیز به آن دسترسی دارد.

برای فایل‌های محلی از آپلود multipart و فیلد file استفاده کنید. برای لینک‌های ByteDance یا URLهای امضاشده موقت تنها در صورت دسترسی عمومی و معتبربودن هنگام ارسال درخواست از file_url استفاده کنید.

پیش از ارسال درخواست، این را از یک سرور عمومی اجرا کنید:

curl -L --max-time 30 -D - -o /dev/null "https://example.com/source.mp3"

درخواست GET باید با HTTP 200 تمام شود، نوع MIME صوتی برگرداند و داده غیرخالی داشته باشد. صفحه ورود، پاسخ HTML و کدهای 401، 403، 404 یا 410 برای سرور قابل استفاده نیستند.

خطای file_url download failed: HTTP 404 معمولاً یعنی امضا منقضی شده، فایل حذف شده یا پارامترهای URL ناقص است.

این آپلود رایگان است. اگر دانلود file_url شکست بخورد، clip_id، وظیفه آهنگ یا فراخوانی تولید ایجاد نمی‌شود و هزینه‌ای کسر نمی‌شود؛ بنابراین بازپرداخت لازم نیست.

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

Headers

برای درخواست‌های JSON:

در درخواست‌های multipart Content-Type را دستی تنظیم نکنید؛ کلاینت آن را خودکار می‌سازد.

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

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

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -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",
    "upload_type": "file_upload"
  }'

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

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.mp3" \
  -F "file_name=source.mp3" \
  -F "upload_type=file_upload" \
  -F "model=suno-v6"

import requests

with open("source.mp3", "rb") as audio:
    response = requests.post(
        "https://www.suno-api.io/api/music/upload-source",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        data={
            "file_name": "source.mp3",
            "upload_type": "file_upload",
            "model": "suno-v6",
        },
        files={"file": ("source.mp3", audio, "audio/mpeg")},
        timeout=300,
    )

response.raise_for_status()
print(response.json())

پاسخ

{
  "clip_id": "uploaded_clip_id",
  "status": "complete",
  "title": "source.mp3",
  "image_url": "https://...",
  "audio_url": "https://...",
  "display_tags": "pop, vocal",
  "inferred_description": "uploaded source audio",
  "clip_metadata": {}
}