docs/ko/API.md

ACE-Step API 클라이언트 문서

언어 / Language / 语言 / 言語: English | 한국어 | 中文 | 日本語

---

이 서비스는 HTTP 기반의 비동기 음악 생성 API를 제공합니다.

기본 워크플로우:

1. POST /release_task를 호출하여 작업을 제출하고 task_id를 획득합니다.
2. POST /query_result를 호출하여 작업 상태가 1(성공) 또는 2(실패)가 될 때까지 배치 쿼리를 수행합니다.
3. 결과에 반환된 GET /v1/audio?path=... URL을 통해 오디오 파일을 다운로드합니다.

---

목차

• 1. 인증
• 2. 응답 형식
• 3. 작업 상태 설명
• 4. 생성 작업 생성
• 5. 작업 결과 배치 조회
• 6. 입력 포맷팅 (Format Input)
• 7. 랜덤 샘플 가져오기
• 8. 사용 가능한 모델 목록
• 9. 서버 통계
• 10. 오디오 파일 다운로드
• 11. 헬스 체크
• 12. 환경 변수

---

1. 인증

API는 선택적으로 API 키 인증을 지원합니다. 활성화된 경우 요청 시 유효한 키를 제공해야 합니다.

인증 방법

두 가지 인증 방법을 지원합니다:

방법 A: 요청 본문의 ai_token

{
  "ai_token": "your-api-key",
  "prompt": "upbeat pop song",
  ...
}

방법 B: Authorization 헤더

curl -X POST http://localhost:8001/release_task \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "upbeat pop song"}'

---

2. 응답 형식

모든 API 응답은 통합 래퍼 형식을 사용합니다:

{
  "data": { ... },
  "code": 200,
  "error": null,
  "timestamp": 1700000000000,
  "extra": null
}

필드	타입	설명
data	any	실제 응답 데이터
code	int	상태 코드 (200=성공)
error	string	에러 메시지 (성공 시 null)
timestamp	int	응답 타임스탬프 (밀리초)
extra	any	추가 정보 (보통 null)

---

3. 작업 상태 설명

작업 상태(status)는 정수로 표현됩니다:

상태 코드	상태 이름	설명
0	대기 중/실행 중	작업이 대기열에 있거나 진행 중임
1	성공	생성이 성공적이며 결과가 준비됨
2	실패	생성 실패

---

4. 생성 작업 생성

4.1 API 정의

• URL: /release_task
• Method: POST
• Content-Type: application/json, multipart/form-data, 또는 application/x-www-form-urlencoded

4.2 요청 파라미터

파라미터 명명 규칙

API는 대부분의 파라미터에 대해 snake_case와 camelCase 명명을 모두 지원합니다. 예:

• audio_duration / duration / audioDuration
• key_scale / keyscale / keyScale
• time_signature / timesignature / timeSignature
• sample_query / sampleQuery / description / desc
• use_format / useFormat / format

또한 메타데이터는 중첩된 객체(metas, metadata, 또는 user_metadata)로 전달할 수 있습니다.

방법 A: JSON 요청 (application/json)

텍스트 파라미터만 전달하거나 서버에 이미 존재하는 오디오 파일 경로를 참조할 때 적합합니다.

기본 파라미터:

파라미터 명	타입	기본값	설명
prompt	string	""	음악 설명 프롬프트 (별칭: caption)
lyrics	string	""	가사 내용
thinking	bool	false	5Hz LM을 사용하여 오디오 코드를 생성할지 여부 (lm-dit 동작)
vocal_language	string	"en"	가사 언어 (en, zh, ja 등)
audio_format	string	"mp3"	출력 형식 (mp3, wav, flac)

샘플/설명 모드 파라미터:

파라미터 명	타입	기본값	설명
sample_mode	bool	false	랜덤 샘플 생성 모드 활성화 (LM을 통해 캡션/가사/메타데이터 자동 생성)
sample_query	string	""	샘플 생성을 위한 자연어 설명 (예: "조용한 저녁을 위한 부드러운 벵골어 사랑 노래"). 별칭: description, desc
use_format	bool	false	LM을 사용하여 제공된 캡션과 가사를 개선/포맷팅합니다. 별칭: format

다중 모델 지원:

파라미터 명	타입	기본값	설명
model	string	null	사용할 DiT 모델 선택 (예: "acestep-v15-turbo", "acestep-v15-turbo-shift3"). /v1/models를 사용하여 가능한 모델 목록을 확인하세요. 지정하지 않으면 기본 모델을 사용합니다.

thinking 의미론 (중요):

• thinking=false:
  • 서버는 audio_code_string을 생성하기 위해 5Hz LM을 사용하지 않습니다.
  • DiT는 text2music 모드에서 실행되며 제공된 audio_code_string을 무시합니다.
• thinking=true:
  • 서버는 audio_code_string을 생성하기 위해 5Hz LM을 사용합니다 (lm-dit 동작).
  • DiT는 향상된 음악 품질을 위해 LM이 생성한 코드를 기반으로 실행됩니다.

메타데이터 자동 완성 (조건부):

use_cot_caption=true 또는 use_cot_language=true이거나 메타데이터 필드가 누락된 경우, 서버는 caption/lyrics를 기반으로 누락된 필드를 채우기 위해 5Hz LM을 호출할 수 있습니다:

• bpm
• key_scale
• time_signature
• audio_duration

사용자가 제공한 값이 항상 우선하며, LM은 비어 있거나 누락된 필드만 채웁니다.

음악 속성 파라미터:

파라미터 명	타입	기본값	설명
bpm	int	null	템포(BPM) 지정, 범위 30-300
key_scale	string	""	키/스케일 (예: "C Major", "Am"). 별칭: keyscale, keyScale
time_signature	string	""	박자 기호 (2/4, 3/4, 4/4, 6/8의 경우 2, 3, 4, 6). 별칭: timesignature, timeSignature
audio_duration	float	null	생성 길이 (초), 범위 10-600. 별칭: duration, target_duration

오디오 코드 (선택 사항):

파라미터 명	타입	기본값	설명
audio_code_string	string or string[]	""	llm_dit를 위한 오디오 시맨틱 토큰(5Hz) 문자열. 별칭: audioCodeString

생성 제어 파라미터:

파라미터 명	타입	기본값	설명
inference_steps	int	8	추론 단계 수. Turbo 모델: 1-20 (권장 8). Base 모델: 1-200 (권장 32-64).
guidance_scale	float	7.0	프롬프트 가이드 계수. Base 모델에서만 유효합니다.
use_random_seed	bool	true	랜덤 시드 사용 여부
seed	int	-1	시드 지정 (use_random_seed=false일 때)
batch_size	int	2	배치 생성 수 (최대 8)

고급 DiT 파라미터:

파라미터 명	타입	기본값	설명
shift	float	3.0	타임스텝 시프트 계수 (범위 1.0-5.0). Turbo 모델이 아닌 Base 모델에서만 유효합니다.
infer_method	string	"ode"	확산 추론 방법: "ode" (Euler, 더 빠름) 또는 "sde" (확률적).
timesteps	string	null	쉼표로 구분된 커스텀 타임스텝 (예: "0.97,0.76,0.615,0.5,0.395,0.28,0.18,0.085,0"). inference_steps와 shift를 재정의합니다.
use_adg	bool	false	ADG (Adaptive Dual Guidance) 사용 (Base 모델 전용)
cfg_interval_start	float	0.0	CFG 적용 시작 비율 (0.0-1.0)
cfg_interval_end	float	1.0	CFG 적용 종료 비율 (0.0-1.0)

5Hz LM 파라미터 (선택 사항, 서버측):

이 파라미터들은 메타데이터 자동 완성 및 (thinking=true일 때) 코드 생성에 사용되는 5Hz LM 샘플링을 제어합니다.

파라미터 명	타입	기본값	설명
lm_model_path	string	null	5Hz LM 체크포인트 디렉토리 이름 (예: acestep-5Hz-lm-0.6B)
lm_backend	string	"vllm"	vllm 또는 pt
lm_temperature	float	0.85	샘플링 온도
lm_cfg_scale	float	2.5	CFG 스케일 (>1일 경우 CFG 활성화)
lm_negative_prompt	string	"NO USER INPUT"	CFG에 사용되는 네거티브 프롬프트
lm_top_k	int	null	Top-k (0/null은 비활성)
lm_top_p	float	0.9	Top-p (>=1은 비활성)
lm_repetition_penalty	float	1.0	반복 페널티

LM CoT (Chain-of-Thought) 파라미터:

파라미터 명	타입	기본값	설명
use_cot_caption	bool	true	CoT 추론을 통해 LM이 입력된 캡션을 다시 쓰거나 개선하도록 합니다. 별칭: cot_caption, cot-caption
use_cot_language	bool	true	CoT를 통해 LM이 가창 언어를 감지하도록 합니다. 별칭: cot_language, cot-language
constrained_decoding	bool	true	구조화된 LM 출력을 위해 FSM 기반 제약 디코딩을 활성화합니다. 별칭: constrainedDecoding, constrained
constrained_decoding_debug	bool	false	제약 디코딩에 대한 디버그 로깅 활성화
allow_lm_batch	bool	true	효율성을 위해 LM 배치 처리 허용

편집/참조 오디오 파라미터 (서버의 절대 경로 필요):

파라미터 명	타입	기본값	설명
reference_audio_path	string	null	참조 오디오 경로 (Style Transfer)
src_audio_path	string	null	소스 오디오 경로 (Repainting/Cover)
task_type	string	"text2music"	작업 유형: text2music, cover, repaint, lego, extract, complete
instruction	string	auto	편집 지침 (제공되지 않으면 task_type에 따라 자동 생성됨)
repainting_start	float	0.0	리페인팅 시작 시간 (초)
repainting_end	float	null	리페인팅 종료 시간 (초), 오디오 끝까지의 경우 -1
audio_cover_strength	float	1.0	오디오 커버 강도 (0.0-1.0). 스타일 전송 작업의 경우 낮은 값(0.2)을 설정합니다.

방법 B: 파일 업로드 (multipart/form-data)

로컬 오디오 파일을 참조 또는 소스 오디오로 업로드해야 할 때 사용합니다.

위의 모든 필드를 폼 필드로 지원할 뿐만 아니라, 다음 파일 필드도 지원합니다:

• reference_audio 또는 ref_audio: (파일) 참조 오디오 파일 업로드
• src_audio 또는 ctx_audio: (파일) 소스 오디오 파일 업로드

참고: 파일을 업로드하면 해당 _path 파라미터는 자동으로 무시되고 시스템은 업로드 후 생성된 임시 파일 경로를 사용합니다.

4.3 응답 예시

{
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "queue_position": 1
  },
  "code": 200,
  "error": null,
  "timestamp": 1700000000000,
  "extra": null
}

---

5. 작업 결과 배치 조회

5.1 API 정의

• URL: /query_result
• Method: POST
• Content-Type: application/json 또는 application/x-www-form-urlencoded

5.2 요청 파라미터

파라미터 명	타입	설명
task_id_list	string (JSON array) or array	조회할 작업 ID 목록

5.3 응답 예시

{
  "data": [
    {
      "task_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": 1,
      "result": "[{\"file\": \"/v1/audio?path=...\", \"wave\": \"\", \"status\": 1, \"create_time\": 1700000000, \"env\": \"development\", \"prompt\": \"upbeat pop song\", \"lyrics\": \"Hello world\", \"metas\": {\"bpm\": 120, \"duration\": 30, \"genres\": \"\", \"keyscale\": \"C Major\", \"timesignature\": \"4\"}, \"generation_info\": \"...\", \"seed_value\": \"12345,67890\", \"lm_model\": \"acestep-5Hz-lm-0.6B\", \"dit_model\": \"acestep-v15-turbo\"}]"
    }
  ],
  "code": 200,
  "error": null,
  "timestamp": 1700000000000,
  "extra": null
}

Result 필드 설명 (result는 JSON 문자열이며, 파싱 후 다음을 포함):

필드	타입	설명
file	string	오디오 파일 URL (/v1/audio 엔드포인트와 함께 사용)
wave	string	파형 데이터 (보통 비어 있음)
status	int	상태 코드 (0=진행 중, 1=성공, 2=실패)
create_time	int	생성 시간 (Unix 타임스탬프)
env	string	환경 식별자
prompt	string	사용된 프롬프트
lyrics	string	사용된 가사
metas	object	메타데이터 (bpm, duration, genres, keyscale, timesignature)
generation_info	string	생성 정보 요약
seed_value	string	사용된 시드 값 (쉼표로 구분)
lm_model	string	사용된 LM 모델 명
dit_model	string	사용된 DiT 모델 명

---

6. 입력 포맷팅 (Format Input)

6.1 API 정의

• URL: /format_input
• Method: POST

이 엔드포인트는 LLM을 사용하여 사용자가 제공한 캡션과 가사를 개선하고 포맷팅합니다.

6.2 요청 파라미터

파라미터 명	타입	기본값	설명
prompt	string	""	음악 설명 프롬프트
lyrics	string	""	가사 내용
temperature	float	0.85	LM 샘플링 온도
param_obj	string (JSON)	"{}"	메타데이터를 포함하는 JSON 객체 (duration, bpm, key, time_signature, language)

6.3 응답 예시

{
  "data": {
    "caption": "Enhanced music description",
    "lyrics": "Formatted lyrics...",
    "bpm": 120,
    "key_scale": "C Major",
    "time_signature": "4",
    "duration": 180,
    "vocal_language": "en"
  },
  "code": 200,
  "error": null,
  "timestamp": 1700000000000,
  "extra": null
}

---

7. 랜덤 샘플 가져오기

7.1 API 정의

• URL: /create_random_sample
• Method: POST

이 엔드포인트는 폼 채우기를 위해 사전 로드된 예제 데이터에서 임의의 샘플 파라미터를 반환합니다.

7.2 요청 파라미터

파라미터 명	타입	기본값	설명
sample_type	string	"simple_mode"	샘플 유형: "simple_mode" 또는 "custom_mode"

---

8. 사용 가능한 모델 목록

8.1 API 정의

• URL: /v1/models
• Method: GET

서버에 로드된 사용 가능한 DiT 모델 목록을 반환합니다.

8.2 응답 예시

{
  "data": {
    "models": [
      {
        "name": "acestep-v15-turbo",
        "is_default": true
      },
      {
        "name": "acestep-v15-turbo-shift3",
        "is_default": false
      }
    ],
    "default_model": "acestep-v15-turbo"
  },
  "code": 200,
  "error": null,
  "timestamp": 1700000000000,
  "extra": null
}

---

9. 서버 통계

9.1 API 정의

• URL: /v1/stats
• Method: GET

서버 런타임 통계를 반환합니다.

---

10. 오디오 파일 다운로드

10.1 API 정의

• URL: /v1/audio
• Method: GET

경로별로 생성된 오디오 파일을 다운로드합니다.

10.2 요청 파라미터

파라미터 명	타입	설명
path	string	오디오 파일의 URL 인코딩된 경로

---

11. 헬스 체크

11.1 API 정의

• URL: /health
• Method: GET

서비스 상태를 반환합니다.

---

12. 환경 변수

API 서버는 환경 변수를 사용하여 구성할 수 있습니다:

서버 구성

변수	기본값	설명
ACESTEP_API_HOST	127.0.0.1	서버 바인드 호스트
ACESTEP_API_PORT	8001	서버 바인드 포트
ACESTEP_API_KEY	(비어 있음)	API 인증 키 (비어 있으면 인증 비활성화)
ACESTEP_API_WORKERS	1	API 워커 스레드 수

모델 구성

변수	기본값	설명
ACESTEP_CONFIG_PATH	acestep-v15-turbo	주 DiT 모델 경로
ACESTEP_DEVICE	auto	모델 로딩 장치
ACESTEP_OFFLOAD_TO_CPU	false	유휴 시 모델을 CPU로 오프로드

LM 구성

변수	기본값	설명
ACESTEP_INIT_LLM	auto	시작 시 LM을 초기화할지 여부 (GPU에 따라 자동 결정)
ACESTEP_LM_MODEL_PATH	acestep-5Hz-lm-0.6B	기본 5Hz LM 모델
ACESTEP_LM_BACKEND	vllm	LM 백엔드 (vllm 또는 pt)

---

에러 처리

HTTP 상태 코드:

• 200: 성공
• 400: 잘못된 요청 (잘못된 JSON, 누락된 필드)
• 401: 미인증 (누락되었거나 잘못된 API 키)
• 429: 서버 바쁨 (대기열이 가득 참)
• 500: 내부 서버 오류

---

모범 사례

1. thinking=true를 사용하여 LM이 향상된 생성 품질의 결과를 얻으세요.
2. 자연어 설명에서 빠른 생성을 위해 sample_query/description을 사용하세요.
3. 캡션/가사가 있지만 LM이 이를 개선하기를 원할 때 use_format=true를 사용하세요.
4. /query_result 엔드포인트를 사용하여 여러 작업 상태를 배치 조회하세요.
5. /v1/stats를 확인하여 서버 부하와 평균 작업 시간을 파악하세요.
6. 보안을 위해 ACESTEP_API_KEY를 설정하여 인증을 활성화하세요.