ACE-Step API 클라이언트 문서

February 6, 2026 · View on GitHub

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

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

기본 워크플로우:

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

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: 내부 서버 오류

모범 사례

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