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 увімкнено, цей виклик тарифікується за подвійною ціною (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