API Replace Section (جایگزینی مقطع)

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

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

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

نقطه پایانی: POST /api/music/replace-section

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

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

Headers

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

startSeconds و endSeconds بر حسب ثانیه هستند و اعشار می‌پذیرند؛ startSeconds باید کوچک‌تر از endSeconds باشد و بازه باید در مدت آهنگ اصلی قرار بگیرد. requestedAt فقط زمانی استفاده می‌شود که باید زمان درخواست را بفرستید، به‌صورت برچسب زمانی Unix بر حسب ثانیه (نه میلی‌ثانیه)؛ معمولاً می‌توان آن را حذف کرد.

جایگزینی هم یک کار ناهمزمان است. clip بازگشتی ممکن است با وضعیت pending شروع شود و خالی‌بودن آدرس صوتی در آن لحظه طبیعی است؛ برای گرفتن نتیجه نهایی از song_id واقعی بازگشتی استفاده کنید.

طول مقطع: دست‌کم 2 ثانیه (مهم)

بازه‌ای که جایگزین می‌شود نمی‌تواند کوتاه‌تر از 2 ثانیه باشد. بر پایه اندازه‌گیری: بازه‌های 1.0 / 1.2 / 1.5 ثانیه همه شکست خوردند و 2.0 ثانیه و بیشتر کار کرد.

وقتی بازه بسیار کوتاه است، پلتفرم «خطای پارامتر» برنمی‌گرداند، بلکه پیامی می‌فرستد که به‌راحتی بد فهمیده می‌شود:

{"error":{"message":"You don't have access to this model. Upgrade your plan to use it.",
          "type":"bad_response_status_code","code":"bad_response_status_code"}}

این جمله مشکل حساب یا طرح نیست — مقطع بسیار کوتاه است. بازه را به بیش از 2 ثانیه برسانید و دوباره بفرستید.

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

curl -X POST https://www.suno-api.io/api/music/replace-section \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "audioId": "clip_id",
    "startSeconds": 30,
    "endSeconds": 45,
    "contextLyrics": "متن زمینه کامل",
    "contextWindowLyrics": "متن زمینه پنجره",
    "infillLyrics": "متن پس از جایگزینی",
    "style": "Mandopop, acoustic",
    "title": "نسخه جایگزین‌شده",
    "negativeTags": "noise"
  }'

پاسخ

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "نسخه جایگزین‌شده",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

فیلدهای سازگار

• audioId / audio_id / clipId / clip_id
• startSeconds / start_seconds / infillStartS / infill_start_s
• endSeconds / end_seconds / infillEndS / infill_end_s
• infillLyrics / infill_lyrics / replacementLyrics / replacement_lyrics
• style / tags
• negativeTags / negative_tags