API 엔드포인트

구간 교체

구간 교체 API

POST

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

이미 만든 곡의 한 부분(잡음이 있는 몇 초나 다르게 부르고 싶은 한 줄 등)을 다시 생성하고, 그 부분이 새로 렌더링된 전체 곡을 받습니다.

작동 방식

완성된 곡에서 시간 구간을 선택합니다. 곡은 그 구간을 중심으로 다시 렌더링되어 전체 길이의 트랙(보통 두 가지 버전)으로 반환되며, 음악 생성과 같은 작업 흐름을 따릅니다.
새 부분이 자연스럽게 이어지도록 구간 양쪽의 약 10초도 함께 다시 렌더링됩니다. 그 밖의 부분은 오디오 재인코딩을 제외하고 그대로 유지됩니다.
구간 규칙(크레딧 차감 전에 검사): 10초 이상, 곡 길이의 50% 이하이면서 480초 이하, infill_end_s는 곡 길이를 넘을 수 없습니다.
lyrics를 보내지 않으면 곡의 단어별 타임스탬프를 바탕으로 구간 안에서 불리는 가사가 자동으로 채워집니다. 다른 가사를 원하면 직접 보내세요.
원곡과 길이가 15초 넘게 다른 결과는 폐기됩니다. 남은 결과가 없으면 작업은 FAILED로 끝나고 크레딧이 환불됩니다. 구간의 시작이나 끝을 몇 초 옮기면 대개 해결됩니다.
요청당 5크레딧이며 요청이 접수될 때 차감됩니다. 검증 단계에서 거부된 요청과 실패한 작업은 자동으로 환불됩니다.
같은 API 키로 /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를 상태가 SUCCESS 또는 FAILED가 될 때까지 5–10초마다 조회하세요. 사용할 API: 작업 상태 조회 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 키

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