Vai al contenuto
Riferimento API
Riferimento API

Suno Sostituisci sezione

Usa l'endpoint di sostituzione sezione per creare un Task asincrono.

Visualizza Markdown
01

Panoramica

Usa l'endpoint di sostituzione sezione con un modello supportato. Utilizza il Task ID restituito per recuperarne lo stato, oppure fornisci callback_url per le consegne documentate di seguito.

Avvio rapido

  1. Crea una Chiave API e impostala come RUNAPI_API_KEY.
  2. Scegli un modello supportato e invia una richiesta POST il cui corpo corrisponda allo schema di quel modello.
  3. Conserva l'ID attività restituito, quindi esegui il polling fino a uno stato terminale o gestisci i callback documentati di seguito.

Endpoint

POST /api/v1/suno/replace_section
URL di base
https://runapi.ai
Versione API
v1
Autenticazione
Authorization: Bearer YOUR_API_TOKEN
02

Modelli supportati

Apri la pagina di un modello per i prezzi correnti, i limiti di frequenza e i dettagli sull'uso commerciale.

03

Schema della richiesta

Corpo JSON

I campi e i valori consentiti dipendono dal modello selezionato. Se fornito, callback_url riceve le notifiche Task documentate di seguito.

Corpo della richiesta12 campi
audio_idstring
Opzionale

ID audio all'interno del task sorgente. Usare con task_id; non combinare con upload_url/model.

callback_urlstring
Opzionale

URL webhook per notifiche asincrone.

full_lyricsstring
Obbligatorio

Testo completo del brano per il contesto.

Vincolo: 5000
infill_end_timenumber
Obbligatorio

Tempo di fine della sezione in secondi; deve essere maggiore di infill_start_time e produrre una durata di sostituzione di almeno 10 secondi.

infill_start_timenumber
Obbligatorio

Tempo di inizio della sezione in secondi; la durata della sostituzione deve essere di almeno 10 secondi.

lyricsstring
Obbligatorio

Testo della sezione sostitutivo.

Vincolo: 5000
modelstring
Opzionale

Slug del modello per l'audio sorgente caricato.

Valori consentiti: suno-v4, suno-v4.5, suno-v4.5-all, suno-v4.5-plus, suno-v5, suno-v5.5
negative_tagsstring
Opzionale

Stili da evitare.

tagsstring
Obbligatorio

Tag di stile o genere.

Vincolo: 1000
task_idstring
Opzionale

ID task sorgente. Da usare con audio_id; non combinare con upload_url/model.

titlestring
Obbligatorio

Titolo del brano.

Vincolo: 80
upload_urlstring
Opzionale

URL dell'audio sorgente caricato. Da usare con model; non combinare con task_id/audio_id.

04

Crea accettazione

HTTP 202

POST /api/v1/suno/replace_section

Schema della risposta
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "task_replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}
05

Polling in elaborazione

HTTP 200

GET /api/v1/suno/replace_section/:id

Schema della risposta
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "track": {
      "properties": {
        "audio_url": {
          "type": "string",
          "x-runapi-generated-media": true
        },
        "duration": {
          "type": "number"
        },
        "id": {
          "type": "string"
        },
        "image_url": {
          "type": "string",
          "x-runapi-generated-media": true
        },
        "lyrics": {
          "type": "string"
        },
        "model_name": {
          "type": "string"
        },
        "stream_audio_url": {
          "type": "string",
          "x-runapi-generated-media": true
        },
        "tags": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  },
  "required": [
    "id",
    "status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}
06

Polling completato

HTTP 200

GET /api/v1/suno/replace_section/:id

Schema della risposta
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "track": {
      "properties": {
        "audio_url": {
          "type": "string",
          "x-runapi-generated-media": true
        },
        "duration": {
          "type": "number"
        },
        "id": {
          "type": "string"
        },
        "image_url": {
          "type": "string",
          "x-runapi-generated-media": true
        },
        "lyrics": {
          "type": "string"
        },
        "model_name": {
          "type": "string"
        },
        "stream_audio_url": {
          "type": "string",
          "x-runapi-generated-media": true
        },
        "tags": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  },
  "required": [
    "id",
    "status",
    "track",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "completed",
  "track": {
    "audio_url": "https://file.runapi.ai/reference-audio.mp3",
    "id": "audio_replaced_section"
  }
}
07

Polling non riuscito

HTTP 200

GET /api/v1/suno/replace_section/:id

Schema della risposta
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "error": "Task processing failed.",
  "id": "tsk_reference_demo",
  "status": "failed"
}
08

Callback cliente: completato

HTTP 200

POST callback_url

Schema della risposta
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "track": {
      "properties": {
        "audio_url": {
          "type": "string",
          "x-runapi-generated-media": true
        },
        "duration": {
          "type": "number"
        },
        "id": {
          "type": "string"
        },
        "image_url": {
          "type": "string",
          "x-runapi-generated-media": true
        },
        "lyrics": {
          "type": "string"
        },
        "model_name": {
          "type": "string"
        },
        "stream_audio_url": {
          "type": "string",
          "x-runapi-generated-media": true
        },
        "tags": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "title": {
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  },
  "required": [
    "id",
    "status",
    "track"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "id": "tsk_reference_demo",
  "status": "completed",
  "track": {
    "audio_url": "https://file.runapi.ai/reference-audio.mp3",
    "id": "audio_replaced_section"
  }
}
09

Callback cliente: fallito

HTTP 200

POST callback_url

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "properties": {
            "code": {
              "type": "string"
            },
            "limit_cents": {
              "type": "integer"
            },
            "message": {
              "type": "string"
            },
            "reset_at": {
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "used_cents": {
              "type": "integer"
            },
            "window": {
              "enum": [
                "1h",
                "1d",
                "7d",
                "daily",
                "weekly",
                "monthly",
                "lifetime"
              ],
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object",
          "unevaluatedProperties": false
        }
      ]
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": {
    "code": "generation_failed",
    "message": "Task processing failed."
  },
  "id": "tsk_reference_demo",
  "status": "failed"
}
10

Errori

HTTP 401

POST /api/v1/suno/replace_section

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Authentication required"
}
11

Errori

HTTP 401

GET /api/v1/suno/replace_section/:id

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Authentication required"
}
12

Errori

HTTP 400

POST /api/v1/suno/replace_section

Schema della risposta
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "Messaggio di errore leggibile.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "Riepilogo di convalida leggibile dall'utente.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "Messaggi di convalida con chiave per campo della richiesta pubblica, con un array di stringhe leggibili dall'utente per ogni campo.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

Esempio di risposta

JSON 
{
  "error": "model must be one of: "
}
13

Errori

HTTP 402

POST /api/v1/suno/replace_section

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Insufficient balance"
}
14

Errori

HTTP 429

POST /api/v1/suno/replace_section

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "API key credit limit exceeded"
}
15

Errori

HTTP 409

POST /api/v1/suno/replace_section

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "The request uses features that are not supported for the selected model"
}
16

Errori

HTTP 429

POST /api/v1/suno/replace_section

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Rate limit reached. Please retry later."
}
17

Errori

HTTP 503

POST /api/v1/suno/replace_section

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Service under maintenance, please try again later"
}
18

Errori

HTTP 504

POST /api/v1/suno/replace_section

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "The request timed out"
}
19

Errori

HTTP 404

GET /api/v1/suno/replace_section/:id

Schema della risposta
JSON 
{
  "properties": {
    "error": {
      "description": "Messaggio di errore leggibile.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Esempio di risposta

JSON 
{
  "error": "Task with id 'tsk_reference_demo' not found"
}
20

Esempi di Codice Generati

Usa cURL direttamente, oppure installa un SDK per il tuo linguaggio. Ogni esempio invia la richiesta validata mostrata in questo riferimento.

Installa

Shell 
pip install runapi-suno
PYTHON 
import os
from runapi.suno import SunoClient

client = SunoClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.replace_section.create(
  upload_url="https://file.runapi.ai/source-audio.mp3",
  model="suno-v5",
  lyrics="New words for this section.",
  tags="acoustic pop",
  title="City Lights",
  infill_start_time=10,
  infill_end_time=20,
  full_lyrics="City lights reflect in the rain. New words for this section."
)