API 接口

片段替换

片段替换 API

POST

https://udioapi.pro/api/v2/replace-section

重新生成已有歌曲中的某一段，例如有杂音的几秒或想换个唱法的一句，返回该段已重新渲染的完整歌曲。

工作方式

在一首已完成的歌曲中选定一个时间窗。系统围绕这个时间窗重新渲染，返回完整时长的歌曲（通常两个版本），任务流程与音乐生成相同。
时间窗两侧各约 10 秒也会被重新渲染，使新片段自然衔接。除此之外的部分保持原样，只是重新编码了音频。
时间窗规则（在扣费前校验）：至少 10 秒；不超过歌曲时长的 50%，且不超过 480 秒；infill_end_s 不能超过歌曲时长。
如果不传 lyrics，系统会根据歌曲的逐字时间戳自动填入时间窗内演唱的歌词。想换成其他歌词时请自行传入。
与原曲时长相差超过 15 秒的结果会被丢弃。如果没有剩余结果，任务以 FAILED 结束并退还积分；将时间窗起点或终点挪动几秒通常就能解决。
每次请求 5 积分，在请求被受理时扣除。校验阶段被拒绝的请求和失败的任务都会自动退款。
只能编辑同一 API Key 下通过 /v2/generate 或 /v2/extend 生成的歌曲。不支持以上传的音频或之前的替换结果作为来源。

快速开始

{
  "origin_task_id": "gen2cd84c4e3ecb94ed6a9137a8f12138ca1bksv",
  "audio_id": "24015dc4-1b81-4033-9f41-cf47a3fae958",
  "infill_start_s": 70,
  "infill_end_s": 85,
  "prompt": "Same melody and arrangement, cleaner vocal in this part"
}

style、title 和 full_lyrics 为可选参数，不传时使用原曲的值。

响应

{
  "code": 200,
  "message": "success",
  "workId": "rep2a15b5bbc14304ca89fcc7b7eae29c8a7bksv",
  "data": {
    "task_id": "rep2a15b5bbc14304ca89fcc7b7eae29c8a7bksv"
  }
}

使用返回的 workId 每 5–10 秒轮询一次，直到状态为 SUCCESS 或 FAILED，接口见任务状态查询 API

参数

必填参数

origin_task_id必填string

要编辑的已完成歌曲的 task_id，即 /v2/generate 或 /v2/extend 返回的值。

audio_id必填string

该任务中歌曲的 id（response_data[].id）。一个任务通常返回两首歌，请选择要编辑的那首。

infill_start_s必填number

片段起点（秒），不小于 0，最多两位小数。

infill_end_s必填number

片段终点（秒）。必须比 infill_start_s 至少晚 10 秒，且不能超过歌曲结尾。

prompt必填string

这一段要如何改变，最多 1000 个字符，例如 "Same melody and arrangement, cleaner vocal in this part"。

可选参数

lyrics可选string

片段内要演唱的歌词，最多 5000 个字符。默认使用时间窗内当前演唱的歌词。

style可选string

结果的音乐风格，最多 1000 个字符。默认使用原曲风格。

title可选string

结果的标题，最多 80 个字符。默认使用原标题。

full_lyrics可选string

编辑后整首歌的完整歌词，最多 5000 个字符。默认使用原歌词。

callback_url可选string

接收最终结果的公网 URL，内容与任务状态中的 response_data 相同。无论是否设置都可以轮询。

结果

任务成功时，response_data 包含新的完整歌曲，每一项都有自己的 id、audio_url 和 duration。如果只有一个版本保持了原曲时长，则只返回这一个。

{
  "code": 200,
  "message": "success",
  "data": {
    "type": "SUCCESS",
    "request_body": {
      "origin_task_id": "gen2cd84c4e3ecb94ed6a9137a8f12138ca1bksv",
      "audio_id": "24015dc4-1b81-4033-9f41-cf47a3fae958",
      "infill_start_s": 70,
      "infill_end_s": 85,
      "prompt": "Same melody and arrangement, cleaner vocal in this part"
    },
    "response_data": [
      {
        "id": "3a8248e4-07b0-4ceb-92b7-34b7615d2552",
        "audio_url": "https://…/3a8248e4-07b0-4ceb-92b7-34b7615d2552.mp3",
        "image_url": "https://…/3a8248e4-07b0-4ceb-92b7-34b7615d2552.jpeg",
        "status": "complete",
        "title": "Harbor Lights",
        "duration": 119.6,
        "model_name": "chirp-v6-mini"
      },
      {
        "id": "eac654a1-5c07-4b6c-896a-59061d323e11",
        "audio_url": "https://…/eac654a1-5c07-4b6c-896a-59061d323e11.mp3",
        "image_url": "https://…/eac654a1-5c07-4b6c-896a-59061d323e11.jpeg",
        "status": "complete",
        "title": "Harbor Lights",
        "duration": 120.84,
        "model_name": "chirp-v6-mini"
      }
    ]
  }
}

当所有结果都改变了歌曲时长，或该片段无法渲染时，任务为 FAILED，积分会被退还：

{
  "code": 200,
  "message": "success",
  "data": {
    "type": "FAILED",
    "response_data": [
      {
        "status": "FAILED",
        "fail_message": "Generation failed. Your credits have been refunded. The result changed the song length (119.6s -> 225.36s / 224.6s), so it was discarded. Try moving the section start or end by a few seconds.",
        "error_message": "Generation failed. Your credits have been refunded. The result changed the song length (119.6s -> 225.36s / 224.6s), so it was discarded. Try moving the section start or end by a few seconds."
      },
      {
        "status": "FAILED",
        "fail_message": "Generation failed. Your credits have been refunded. The result changed the song length (119.6s -> 225.36s / 224.6s), so it was discarded. Try moving the section start or end by a few seconds.",
        "error_message": "Generation failed. Your credits have been refunded. The result changed the song length (119.6s -> 225.36s / 224.6s), so it was discarded. Try moving the section start or end by a few seconds."
      }
    ]
  }
}

代码示例

cURL

curl -X POST "https://udioapi.pro/api/v2/replace-section" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_task_id": "gen2cd84c4e3ecb94ed6a9137a8f12138ca1bksv",
    "audio_id": "24015dc4-1b81-4033-9f41-cf47a3fae958",
    "infill_start_s": 70,
    "infill_end_s": 85,
    "prompt": "Same melody and arrangement, cleaner vocal in this part"
  }'

JavaScript

const response = await fetch('https://udioapi.pro/api/v2/replace-section', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "origin_task_id": "gen2cd84c4e3ecb94ed6a9137a8f12138ca1bksv",
    "audio_id": "24015dc4-1b81-4033-9f41-cf47a3fae958",
    "infill_start_s": 70,
    "infill_end_s": 85,
    "prompt": "Same melody and arrangement, cleaner vocal in this part"
  })
});

const { workId } = await response.json();
// Poll https://udioapi.pro/api/v2/feed?workId=... every 5-10 seconds until SUCCESS or FAILED.

Python

import requests

response = requests.post(
    "https://udioapi.pro/api/v2/replace-section",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
      "origin_task_id": "gen2cd84c4e3ecb94ed6a9137a8f12138ca1bksv",
      "audio_id": "24015dc4-1b81-4033-9f41-cf47a3fae958",
      "infill_start_s": 70,
      "infill_end_s": 85,
      "prompt": "Same melody and arrangement, cleaner vocal in this part"
    },
)
work_id = response.json()["workId"]
# Poll https://udioapi.pro/api/v2/feed?workId=... every 5-10 seconds until SUCCESS or FAILED.

错误响应

400 · 片段短于 10 秒

{
  "code": 400,
  "message": "The section must be at least 10 seconds long (requested 9.99s)."
}

400 · 片段超过歌曲时长的 50%

{
  "code": 400,
  "message": "The section can cover at most 50% of the song and 480s (max 59.8s for this song, requested 65s)."
}

400 · 片段终点超出歌曲结尾

{
  "code": 400,
  "message": "\"infill_end_s\" must not exceed the song length (119.6s)."
}

400 · 原任务不存在或未完成

{
  "code": 400,
  "message": "The provided \"origin_task_id\" is invalid or could not be found. Use the task_id of a completed song generated with your API key."
}

400 · audio_id 不属于该任务

{
  "code": 400,
  "message": "\"audio_id\" 1234 does not belong to this task. Use one of the song ids returned for \"origin_task_id\"."
}

400 · 不支持上传的音频

{
  "code": 400,
  "message": "Only songs generated with this API can be edited: send \"origin_task_id\" and \"audio_id\", without \"upload_url\" or \"model\"."
}

402 · 积分不足

{
  "code": 402,
  "message": "No available credits"
}

401 · API Key 无效

{
  "code": 401,
  "message": "Invalid API key"
}