替换音乐分区

本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。

接口

POST /jobs/createTask

完整 URL: https://ai.modelfold.online/v1/jobs/createTask

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

文档已更新

若你此前已完成对接，仍可前往旧版文档查看：旧版地址 (https://ai.modelfold.online/docs/)

替换现有音乐的指定时间段。

使用指南

此接口可以替换已生成音乐中的特定时间段
需要提供原始音乐的任务 ID 和要替换的时间范围
替换后的音频会与原音乐自然融合

参数详情

始终必填：prompt、tags、title、infill_start_s、infill_end_s、full_lyrics
lyrics 为替换片段的歌词，可选，V6 最多 5000 字符
可选：negative_tags、vocal_gender、style_weight、weirdness_constraint、audio_weight、variety、persona_id、persona_model

时间范围说明

infill_start_s 必须小于 infill_end_s
时间值精确到小数点后 2 位，例如：10.50 秒
替换时间范围至少为 10 秒
替换时长建议不超过原音乐总时长的 50%

开发者注意事项

替换片段会根据提供的 prompt 和 tags 重新生成
生成的替换片段会自动与原音乐前后部分融合
生成的文件将保留 14 天
查询任务状态使用与生成音乐相同的接口：获取任务详情

请求参数

请求体 (application/json)

参数	类型	必填	说明
`model`	`string`	是	用于生成任务的模型名称。该字段为必填项。此接口必须使用 `ai-music-api/replace-section` 模型。可选值：`ai-music-api/replace-section`。示例：`ai-music-api/replace-section`。
`callBackUrl`	`string`	否	接收生成任务完成更新的 URL。可选但建议在生产环境中使用。 - 当生成完成时，系统将向此 URL POST 任务状态和结果 - 回调包含生成的 URL 和任务信息 - 您的回调端点应接受包含结果的 JSON 负载的 POST 请求 - 或者，用 GET /api/v1/jobs/recordInfo?taskId=... 轮询（见“获取任务详情”）。Suno 音频类任务的结果在 data.response.data[]（audio_url、stream_audio_url、image_url、id、duration）。 - 为确保回调安全性，请参阅 Webhook 校验指南了解签名验证实现方法示例：`https://api.example.com/callback`。
`input`	`object	object`	是
`input.prompt`	`string`	是	替换后的歌词。必填。示例：`A calm and relaxing piano track.`。
`input.tags`	`string`	是	音乐的风格标签，如爵士、电子等。必填。示例：`Jazz`。
`input.title`	`string`	是	音乐的标题。必填。示例：`Relaxing Piano`。
`input.negative_tags`	`string`	否	排除的音乐风格，用于避免特定风格元素出现在替换片段中示例：`Rock`。
`input.infill_start_s`	`number`	是	开始替换的时间点（秒），保留2位小数。必填。必须小于 infill_end_s，且 infill_end_s 与 infill_start_s 的时间差必须至少为10 秒。示例：`10.5`。
`input.infill_end_s`	`number`	是	结束替换的时间点（秒），保留2位小数。必填。必须大于 infill_start_s，且 infill_end_s 与 infill_start_s 的时间差必须至少为10 秒。示例：`20.75`。
`input.full_lyrics`	`string`	是	修改后的完整歌词，包含修改和未修改歌词的合并。必填。此参数包含在分区替换后整首歌曲将使用的完整歌词文本。示例：`[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词`。
`input.lyrics`	`string`	否	替换片段的歌词。可选。 - V6、V6_MINI 和 V6_WILD：最多 5000 字符。示例：`[副歌]\n此部分的修改歌词`。
`input.vocal_gender`	`string`	否	人声性别偏好。可选。'm' 表示男声，'f' 表示女声。根据实践，此参数只能加强概率，但不能保证一定遵循男女声的指令。可选值：`m` / `f`。示例：`m`。
`input.style_weight`	`number`	否	对指定风格的遵循强度。可选。范围 0–1，保留两位小数。示例：`0.65`。
`input.weirdness_constraint`	`number`	否	控制实验性/创意偏离程度。可选。范围 0–1，保留两位小数。示例：`0.65`。
`input.audio_weight`	`number`	否	音频要素相对权重。可选。范围 0–1，保留两位小数。示例：`0.65`。
`input.variety`	`integer`	否	控制生成结果的多样性和风格差异程度。可选。范围 0–4，取整数，默认值为 1。 - `0`：off（关），完全关闭，严格用同一风格 - `1`：normal（普通），默认值，在稳定性和多样性之间保持平衡 - `2`：high（高），生成风格差异明显的结果 - `3`：extra（额外），提供更高程度的变化，鼓励大胆探索不同风格 - `4`：max（最大），最大程度增加多样性，生成结果可能具有非常明显的风格差异默认值：`1`。示例：`1`。
`input.persona_id`	`string`	否	用于应用于生成音乐的 Persona ID 或 Voice ID。可选。使用此选项可将特定的 Persona 风格应用于您的音乐生成。要生成 Persona ID，请使用生成 Persona 端点，基于生成的音乐创建个性化的音乐 Persona。要生成 Voice ID，请使用生成 Voice 端点。示例：`persona_123`。
`input.persona_model`	`string`	否	persona 模型。可选。`style_persona` 用于 Generate Persona ID，`voice_persona` 用于 Suno Voice ID。默认 `style_persona`。仅 V5（已废弃）、V5.5（已废弃）、V6、V6_MINI、V6_WILD 可用。默认值：`"style_persona"`。可选值：`style_persona` / `voice_persona`。示例：`style_persona`。

请求示例

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": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
    "lyrics": "[副歌]\n此部分的修改歌词",
    "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": "[主歌1]\n原始歌词内容\n[副歌]\n此部分的修改歌词\n[主歌2]\n更多原始歌词",
    "lyrics": "[副歌]\n此部分的修改歌词",
    "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"
  }
}

响应

200 — 请求成功

参数	类型	必填	说明
`code`	`integer`	否	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。可选值：`200` / `401` / `402` / `404` / `409` / `422` / `429` / `451` / `455` / `500`。示例：`200`。
`msg`	`string`	否	当 code != 200 时的错误信息示例：`success`。
`data`	`object`	否	—
`data.taskId`	`string`	否	任务 ID，用于追踪任务状态。用 GET /api/v1/jobs/recordInfo?taskId=... 轮询（见“获取任务详情”）。Suno 音频类任务的结果在 data.response.data[]（audio_url、stream_audio_url、image_url、id、duration）。示例：`5c79****be8e`。

json

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

回调

audioGenerated

回调地址：{request.body#/callBackUrl}（即请求体里的 callBackUrl）。

当音频生成完成时，系统会调用此回调通知结果。

回调示例

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": "[Verse] 夜晚城市 灯火辉煌",
        "model_name": "chirp-v3-5",
        "title": "钢铁侠",
        "tags": "electrifying, rock",
        "createTime": 1791200596437,
        "duration": 198.44
      },
      {
        "id": "bd15****1873",
        "audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "image_url": "https://example.cn/****.jpeg",
        "prompt": "[Verse] 夜晚城市 灯火辉煌",
        "model_name": "chirp-v3-5",
        "title": "钢铁侠",
        "tags": "electrifying, rock",
        "createTime": 1791200596437,
        "duration": 228.28
      }
    ]
  }
}

回调体参数

参数	类型	必填	说明
`code`	`integer`	否	状态码示例：`200`。
`msg`	`string`	否	返回消息示例：`All generated successfully`。
`data`	`object`	否	—
`data.callbackType`	`string`	否	回调类型：text（文本生成完成）、first（第一首生成完成）、complete（全部生成完成）可选值：`text` / `first` / `complete`。示例：`text`。
`data.task_id`	`string`	否	任务ID
`data.data`	`array<object>`	否	—
`data.data[].id`	`string`	否	音频唯一标识 (audioId)
`data.data[].audio_url`	`string`	否	音频文件URL
`data.data[].stream_audio_url`	`string`	否	流式音频URL
`data.data[].image_url`	`string`	否	封面图片URL
`data.data[].prompt`	`string`	否	生成提示词/歌词
`data.data[].model_name`	`string`	否	使用的模型名称
`data.data[].title`	`string`	否	音乐标题
`data.data[].tags`	`string`	否	音乐标签
`data.data[].createTime`	`integer`	否	创建时间（Unix 毫秒时间戳）
`data.data[].duration`	`number`	否	音频时长（秒）

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
      }
    ]
  }
}

替换音乐分区 ​

接口 ​

使用指南 ​

参数详情 ​

时间范围说明 ​

开发者注意事项 ​

请求参数 ​

请求体 (application/json) ​

请求示例 ​

响应 ​

200 — 请求成功 ​

回调 ​

audioGenerated ​

回调示例 ​

替换音乐分区

接口

使用指南

参数详情

时间范围说明

开发者注意事项

请求参数

请求体 (application/json)

请求示例

响应

200 — 请求成功

回调

audioGenerated

回调示例