Replace Music Section

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /jobs/createTask

Full URL: https://ai.modelfold.online/v1/jobs/createTask

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

Document updated

If you have already completed the integration process previously, you can still access the old version document at: Old version address (https://ai.modelfold.online/docs/en/suno-api/replace-section)

Replace a specific time segment within existing music.

This interface can replace specific time segments in already generated music. It requires providing the original music's task ID and the time range to be replaced. The replaced audio will naturally blend with the original music. This endpoint is always custom mode.

Parameter Details

Always required: prompt, tags, title, infill_start_s, infill_end_s, full_lyrics
lyrics is optional lyrics for the replaced segment. V6 maximum 5000 characters
Optional: negative_tags, vocal_gender, style_weight, weirdness_constraint, audio_weight, variety, persona_id, persona_model

Time Range Instructions

infill_start_s must be less than infill_end_s.
Time values are precise to 2 decimal places, e.g., 10.50 seconds.
The replacement time must be at least 10 seconds.
Replacement duration should not exceed 50% of the original music's total duration.

Developer Notes

Replacement segments will be regenerated based on the provided prompt and tags.
Generated replacement segments will automatically blend with the original music's preceding and following parts.
Generated files will be retained for 14 days.

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
`model`	`string`	Yes	The model name used to generate the task. This field is required. This endpoint must use the `ai-music-api/replace-section` model. Allowed values：`ai-music-api/replace-section`。示例：`ai-music-api/replace-section`。
`callBackUrl`	`string`	No	The URL to receive updates when the generation task is completed. Optional, but recommended for production environments. - When generation is complete, the system will POST the task status and results to this URL - The callback includes the generated URL and task information - Your callback endpoint should accept POST requests with a JSON payload containing the results - Alternatively, poll GET /api/v1/jobs/recordInfo?taskId=... (see Get Task Details). For Suno audio tasks the tracks are in data.response.data[] (audio_url, stream_audio_url, image_url, id, duration). - To ensure callback security, refer to the Webhook Verification Guide for signature verification implementation 示例：`https://api.example.com/callback`。
`input`	`object	object`	Yes
`input.prompt`	`string`	Yes	The lyrics after replacement. Required. 示例：`A calm and relaxing piano track.`。
`input.tags`	`string`	Yes	Style tags for the music, such as jazz or electronic. Required. 示例：`Jazz`。
`input.title`	`string`	Yes	The title of the music. Required. 示例：`Relaxing Piano`。
`input.negative_tags`	`string`	No	Music styles to exclude, used to prevent specific stylistic elements from appearing in the replacement section. 示例：`Rock`。
`input.infill_start_s`	`number`	Yes	The point in time, in seconds, at which replacement starts, rounded to 2 decimal places. Required. Must be less than infill_end_s, and the difference between infill_end_s and infill_start_s must be at least 10 seconds. 示例：`10.5`。
`input.infill_end_s`	`number`	Yes	The point in time, in seconds, at which replacement ends, rounded to 2 decimal places. Required. Must be greater than infill_start_s, and the difference between infill_end_s and infill_start_s must be at least 10 seconds. 示例：`20.75`。
`input.full_lyrics`	`string`	Yes	The complete modified lyrics, combining the modified and unmodified lyrics. Required. This parameter contains the complete lyrics text that will be used for the entire song after section replacement. 示例：`[Verse 1]\nOriginal lyrics content\n[Chorus]\nModified lyrics for this section\n[Verse 2]\nMore original lyrics`。
`input.lyrics`	`string`	No	Lyrics for the replaced segment. Optional. - V6, V6_MINI, and V6_WILD: Maximum 5000 characters. 示例：`[Chorus]\nModified lyrics for this section`。
`input.vocal_gender`	`string`	No	Vocal gender preference. Optional. 'm' for male, 'f' for female. Based on practice, this parameter can only increase the probability but cannot guarantee adherence to male/female voice instructions. Allowed values：`m` / `f`。示例：`m`。
`input.style_weight`	`number`	No	Adherence strength to specified style. Optional. Range 0–1, up to 2 decimal places. 示例：`0.65`。
`input.weirdness_constraint`	`number`	No	Controls experimental/creative deviation level. Optional. Range 0–1, up to 2 decimal places. 示例：`0.65`。
`input.audio_weight`	`number`	No	Relative weight of audio elements. Optional. Range 0–1, up to 2 decimal places. 示例：`0.65`。
`input.variety`	`integer`	No	Controls the diversity and stylistic variation of generated results. Optional. Integer range 0–4, default 1. - `0`: off (exact style) — fully off, strictly the same style - `1`: normal (balanced variety) — default, balances stability and diversity - `2`: high (distinct styles) — produces results with clearly different styles - `3`: extra (bold exploration) — higher variation, encourages bold exploration of different styles - `4`: max (unreasonably varied) — maximum diversity; results may differ in style very significantly Default：`1`。示例：`1`。
`input.persona_id`	`string`	No	Persona ID or Voice ID to apply to the generated music. Optional. Use this to apply a specific persona style to your music generation. To generate a Persona ID, use the Generate Persona endpoint to create a personalized music Persona based on generated music. To generate a Voice ID, use the Generate Voice endpoint. 示例：`persona_123`。
`input.persona_model`	`string`	No	Persona model. Optional. Use `style_persona` for Generate Persona IDs, or `voice_persona` for Suno Voice IDs. Default: `style_persona`. Available for V5 (Discontinued), V5_5 (Discontinued), V6, V6_MINI, and V6_WILD. Default：`"style_persona"`。 Allowed values：`style_persona` / `voice_persona`。示例：`style_persona`。

Request Example

bash

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ai-music-api/replace-section",
  "callBackUrl": "https://example.com/callback",
  "input": {
    "task_id": "2fac****9f72",
    "audio_id": "e231****-****-****-****-****8cadc7dc",
    "prompt": "A calm and relaxing piano track.",
    "tags": "Jazz",
    "title": "Relaxing Piano",
    "negative_tags": "Rock",
    "infill_start_s": 10.5,
    "infill_end_s": 20.75,
    "full_lyrics": "[Verse 1]\nOriginal lyrics here\n[Chorus]\nModified lyrics for this section\n[Verse 2]\nMore original lyrics",
    "lyrics": "[Chorus]\nModified lyrics for this section",
    "variety": 1,
    "vocal_gender": "m",
    "style_weight": 0.65,
    "weirdness_constraint": 0.65,
    "audio_weight": 0.65,
    "persona_id": "persona_123",
    "persona_model": "style_persona"
  }
}'

json

{
  "model": "ai-music-api/replace-section",
  "callBackUrl": "https://example.com/callback",
  "input": {
    "task_id": "2fac****9f72",
    "audio_id": "e231****-****-****-****-****8cadc7dc",
    "prompt": "A calm and relaxing piano track.",
    "tags": "Jazz",
    "title": "Relaxing Piano",
    "negative_tags": "Rock",
    "infill_start_s": 10.5,
    "infill_end_s": 20.75,
    "full_lyrics": "[Verse 1]\nOriginal lyrics here\n[Chorus]\nModified lyrics for this section\n[Verse 2]\nMore original lyrics",
    "lyrics": "[Chorus]\nModified lyrics for this section",
    "variety": 1,
    "vocal_gender": "m",
    "style_weight": 0.65,
    "weirdness_constraint": 0.65,
    "audio_weight": 0.65,
    "persona_id": "persona_123",
    "persona_model": "style_persona"
  }
}

Response

200 — Request successful

参数	类型	必填	说明
`code`	`integer`	否	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：`200` / `401` / `402` / `404` / `409` / `422` / `429` / `451` / `455` / `500`。示例：`200`。
`msg`	`string`	否	Error message when code != 200 示例：`success`。
`data`	`object`	否	—
`data.taskId`	`string`	否	Task ID for tracking task status. Poll GET /api/v1/jobs/recordInfo?taskId=... (see Get Task Details). For Suno audio tasks the tracks are in data.response.data[] (audio_url, stream_audio_url, image_url, id, duration). 示例：`5c79****be8e`。

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

Callback

audioGenerated

Callback URL: {request.body#/callBackUrl} (the callBackUrl in the request body).

When audio generation is complete, the system will call this callback to notify the result.

Callback Example

json

{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "2fac****9f72",
    "data": [
      {
        "id": "e231****-****-****-****-****8cadc7dc",
        "audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "image_url": "https://example.cn/****.jpeg",
        "prompt": "A calm and relaxing piano track.",
        "model_name": "chirp-v3-5",
        "title": "Relaxing Piano",
        "tags": "Jazz",
        "createTime": 1791200596437,
        "duration": 198.44
      }
    ]
  }
}

Callback body parameters

参数	类型	必填	说明
`code`	`integer`	否	Status code 示例：`200`。
`msg`	`string`	否	Return message 示例：`All generated successfully`。
`data`	`object`	否	—
`data.callbackType`	`string`	否	Callback type: text (text generation complete), first (first song complete), complete (all complete) Allowed values：`text` / `first` / `complete`。示例：`text`。
`data.task_id`	`string`	否	Task ID
`data.data`	`array<object>`	否	—
`data.data[].id`	`string`	否	Audio unique identifier (audioId)
`data.data[].audio_url`	`string`	否	Audio file URL
`data.data[].stream_audio_url`	`string`	否	Streaming audio URL
`data.data[].image_url`	`string`	否	Cover image URL
`data.data[].prompt`	`string`	否	Generation prompt/lyrics
`data.data[].model_name`	`string`	否	Model name used
`data.data[].title`	`string`	否	Music title
`data.data[].tags`	`string`	否	Music tags
`data.data[].createTime`	`integer`	否	Creation time (Unix timestamp in milliseconds)
`data.data[].duration`	`number`	否	Audio duration (seconds)

json

{
  "code": 200,
  "msg": "All generated successfully",
  "data": {
    "callbackType": "text",
    "task_id": "",
    "data": [
      {
        "id": "",
        "audio_url": "https://your-domain.com/input.png",
        "stream_audio_url": "https://your-domain.com/input.png",
        "image_url": "https://your-domain.com/input.png",
        "prompt": "A serene mountain landscape at sunrise",
        "model_name": "model-name",
        "title": "",
        "tags": "",
        "createTime": 0,
        "duration": 0
      }
    ]
  }
}

Replace Music Section ​

Endpoint ​

Parameter Details ​

Time Range Instructions ​

Developer Notes ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request successful ​

Callback ​

audioGenerated ​

Callback Example ​

Replace Music Section

Endpoint

Parameter Details

Time Range Instructions

Developer Notes

Request Parameters

Body (application/json)

Request Example

Response

200 — Request successful

Callback

audioGenerated

Callback Example