API Replace Section (zamiana fragmentu)

Zaktualizowano 2026-09-18 · zespół Suno-API

Opis punktu końcowego

Replace Section regeneruje w miejscu jeden przedział czasu istniejącego utworu. Nadaje się do poprawienia wersu tekstu lub wymiany fragmentu.

Punkt końcowy: POST /api/music/replace-section

Rozliczenie: Płatne, obecnie domyślnie 0,6 ¥ za wywołanie. Faktycznie pobierana kwota zależy od bieżącej konfiguracji cen w panelu administracyjnym.

Max Mode / Variety: ten punkt końcowy obsługuje opcjonalne parametry max_mode i variety (0-4). Przy włączonym max_mode to wywołanie jest rozliczane po podwójnej cenie (0,6 → 1,2 ¥ za wywołanie); variety nie kosztuje nic dodatkowo. Znaczenie i sposób wysyłania opisano w sekcji „Parametry zaawansowane” Przeglądu nowego API.

Czasy oczekiwania i limity czasu (ważne): to punkt końcowy synchroniczny — zamówienie zostaje przyjęte i przekazane do generowania dopiero, gdy przyjdzie odpowiedź. Z pomiarów: większość żądań odpowiada w 1-3 sekundy, około 10% przekracza 30 sekund, a najdłuższe trwa około 230 sekund. Ustaw limit czasu klienta na 300 sekund lub więcej; brak odpowiedzi nie oznacza, że nic nie zostało wygenerowane, a ponawianie od razu po limicie czasu duplikuje zamówienie i pobiera opłatę ponownie. Jeśli połączenie się zerwało, sprawdź później przez GET /api/music/songs. Zobacz „Czasy oczekiwania i ustawienia limitu czasu” w Przeglądzie nowego API.

Parametry żądania

Headers

Parametry treści

startSeconds i endSeconds podaje się w sekundach i można użyć ułamków; startSeconds musi być mniejsze niż endSeconds, a przedział musi mieścić się w długości oryginalnego utworu. requestedAt służy tylko do przekazania czasu żądania jako znacznik czasu Unix w sekundach (nie w milisekundach); zwykle można je pominąć.

Zamiana to również zadanie asynchroniczne. Zwrócony clip może zaczynać od stanu pending, a pusty adres audio w tym momencie jest normalny; użyj zwróconego prawdziwego song_id, aby pobrać wynik końcowy.

Długość fragmentu: co najmniej 2 sekundy (ważne)

Zamieniany przedział nie może być krótszy niż 2 sekundy. Z pomiarów: przedziały 1,0 / 1,2 / 1,5 sekundy kończyły się niepowodzeniem, a 2,0 sekundy i więcej działały.

Gdy przedział jest zbyt krótki, platforma nie odpowiada „błędem parametru”, lecz komunikatem, który łatwo zrozumieć błędnie:

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

To zdanie nie oznacza problemu z kontem ani planem — fragment jest zbyt krótki. Wydłuż przedział powyżej 2 sekund i wyślij ponownie.

Przykład żądania

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": "pełny tekst kontekstowy",
    "contextWindowLyrics": "tekst kontekstowy okna",
    "infillLyrics": "tekst zamiany",
    "style": "Mandopop, acoustic",
    "title": "Wersja zamieniona",
    "negativeTags": "noise"
  }'

Odpowiedź

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "Wersja zamieniona",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

Pola zgodne

• 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