API Replace Section (thay thế đoạn)

Cập nhật 2026-09-18 · nhóm Suno-API

Mô tả endpoint

Replace Section tạo lại tại chỗ một khoảng thời gian của bài hát đã có. Phù hợp để sửa một câu lời hoặc thay một đoạn.

Endpoint: POST /api/music/replace-section

Tính phí: Có phí, hiện mặc định 0,6 ¥ mỗi lần gọi. Số tiền thực trừ tuân theo cấu hình giá hiện tại trong phần quản trị.

Max Mode / Variety: endpoint này hỗ trợ hai tham số tùy chọn max_mode và variety (0-4). Khi bật max_mode, lần gọi này bị tính gấp đôi (0,6 → 1,2 ¥ mỗi lần); variety không phát sinh phí thêm. Ý nghĩa và cách gửi xem mục "Tham số nâng cao" trong Tổng quan API mới.

Thời gian chờ và timeout (quan trọng): đây là endpoint đồng bộ — đơn chỉ được tiếp nhận và đưa vào tạo nhạc khi phản hồi trả về. Theo đo đạc, phần lớn yêu cầu trả về trong 1-3 giây, khoảng 10% mất hơn 30 giây và lâu nhất khoảng 230 giây. Hãy đặt timeout phía client từ 300 giây trở lên; không nhận được phản hồi không có nghĩa là chưa tạo gì, và đừng thử lại ngay sau khi timeout (sẽ trùng đơn và bị tính phí hai lần). Nếu kết nối bị ngắt, hãy kiểm tra lại sau bằng GET /api/music/songs. Xem "Thời gian chờ và thiết lập timeout" trong Tổng quan API mới.

Tham số yêu cầu

Headers

Tham số body

startSeconds, endSeconds tính bằng giây và cho phép số thập phân; startSeconds phải nhỏ hơn endSeconds và khoảng phải nằm trong thời lượng bài gốc. requestedAt chỉ dùng khi cần truyền thời điểm yêu cầu, theo timestamp Unix tính bằng giây (không phải mili giây); thường có thể bỏ qua.

Thay thế cũng là tác vụ bất đồng bộ. Clip trả về có thể bắt đầu ở trạng thái pending, khi đó địa chỉ âm thanh rỗng là bình thường; hãy dùng song_id thật được trả về để tra kết quả cuối cùng.

Độ dài đoạn: tối thiểu 2 giây (quan trọng)

Khoảng cần thay không được ngắn hơn 2 giây. Đo đạc: các khoảng 1,0 / 1,2 / 1,5 giây đều thất bại, còn 2,0 giây trở lên thì bình thường.

Khi khoảng quá ngắn, nền tảng không trả về "lỗi tham số" mà trả một thông báo dễ bị hiểu sai:

{"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"}}

Câu đó không phải vấn đề tài khoản hay gói dịch vụ — mà là đoạn quá ngắn. Hãy kéo dài khoảng lên trên 2 giây rồi gửi lại.

Ví dụ yêu cầu

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": "lời ngữ cảnh đầy đủ",
    "contextWindowLyrics": "lời ngữ cảnh cửa sổ",
    "infillLyrics": "lời sau khi thay",
    "style": "Mandopop, acoustic",
    "title": "Bản thay thế",
    "negativeTags": "noise"
  }'

Phản hồi

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "Bản thay thế",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

Trường tương thích

• 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