튜토리얼

MiniMax Music API(minimax-music-1.5) 사용 방법: curl, Python 및 실행 가능한 요청

Jul 8, 2026

이 가이드에서는 hiapi의 통합 작업 API에서 minimax-music-1.5를 사용하여 스타일 프롬프트와 가사로 보컬, 악기, 곡 구조를 포함한 완전한 곡 한 곡을 생성하는 방법을 설명합니다. 아래 내용은 모두 실제 엔드포인트에서 검증되었으며, 그대로 복사하여 붙여넣고 실행할 수 있습니다.

무엇을 만들고, 무엇을 준비해야 하나요

목표: 음악 스타일에 대한 텍스트 설명과 가사를 제출한 뒤, 다운로드 가능한 오디오 트랙을 받는 것입니다.

필요한 것은 단 하나, hiapi API 키입니다. 대시보드에서 발급받으세요. 키는 sk-로 시작합니다. 아래 모든 예시는 이 키가 환경 변수에 저장되어 있다고 가정합니다:

export HIAPI_KEY="sk-your-key-here"

hiapi의 음악 생성은 다른 모든 모델과 동일한 비동기 작업 인터페이스를 사용합니다. POST /v1/tasks로 작업을 생성한 다음, GET /v1/tasks/<taskId>를 폴링하거나 작업 완료 시 콜백을 받습니다.

입력 스키마(검증됨)

minimax-music-1.5는 input에서 다음 필드만 허용합니다. 그 외의 필드는 400으로 거부됩니다:

필드	필수 여부	타입	제약
`prompt`	예	string	10–300자. 곡 스타일, 분위기, 악기 편성, 보컬 스타일을 설명합니다.
`lyrics`	예	string	10–600자. 노래할 가사이며 `[Verse]`, `[Chorus]` 등의 섹션 태그를 지원합니다.
`sample_rate`	아니오	integer	`16000`, `24000`, `32000`, `44100` 중 하나.
`bitrate`	아니오	integer	`32000`, `64000`, `128000`, `256000` 중 하나.

흔히 실수하는 지점이 두 가지 있습니다:

prompt와 lyrics는 모두 필수입니다. prompt는 어떻게 들리는지를 제어하고, lyrics는 무엇을 노래하는지를 제어합니다. 둘 중 하나라도 없으면 invalid input: ... missing required field가 반환됩니다.
스키마는 엄격합니다. 다른 음악 API에서 있을 법한 필드인 duration, seed, format, instrumental은 허용되지 않습니다. 이를 전송하면 additional properties ... not allowed가 반환됩니다.

최소 실행 예시: curl

작업 생성:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-1.5",
    "input": {
      "prompt": "따뜻한 여성 보컬이 돋보이는 경쾌한 어쿠스틱 팝, 부드러운 기타와 가벼운 퍼커션",
      "lyrics": "[Verse]\n조용한 거리에 아침 햇살\n커피 김과 규칙적인 리듬\n[Chorus]\n우리는 계속 나아가, 길을 찾아\n매일 한 걸음씩 천천히",
      "sample_rate": 44100,
      "bitrate": 256000
    }
  }'

생성에 성공하면 작업 id가 반환됩니다:

{"code": 200, "data": {"taskId": "task_abc123..."}}

그런 다음 작업이 종료 상태에 도달할 때까지 폴링합니다:

curl https://api.hiapi.ai/v1/tasks/task_abc123 \
  -H "Authorization: Bearer $HIAPI_KEY"

작업이 실행되는 동안에는 종료되지 않은 status가 보입니다. 완료되면 status가 success로 바뀌고 오디오 URL이 output에 나타납니다:

{
  "code": 200,
  "data": {
    "taskId": "task_abc123",
    "status": "success",
    "output": [{"url": "https://.../track.mp3"}]
  }
}

파일은 가능한 한 빨리 다운로드하세요. 출력 URL은 만료되므로 영구 저장소가 아닌 수령 창으로 생각해야 합니다:

curl -o track.mp3 "https://.../track.mp3"

전체 Python 스크립트: 제출, 폴링, 다운로드

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_KEY']}",
    "Content-Type": "application/json",
}

def create_task() -> str:
    payload = {
        "model": "minimax-music-1.5",
        "input": {
            "prompt": ("따뜻한 여성 보컬이 돋보이는 경쾌한 어쿠스틱 팝, "
                       "부드러운 기타와 가벼운 퍼커션"),
            "lyrics": ("[Verse]\n조용한 거리에 아침 햇살\n"
                       "커피 김과 규칙적인 리듬\n"
                       "[Chorus]\n우리는 계속 나아가, 길을 찾아\n"
                       "매일 한 걸음씩 천천히"),
            "sample_rate": 44100,
            "bitrate": 256000,
        },
    }
    r = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    data = r.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = (r.json().get("data") or {})
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

def download(url: str, path: str = "track.mp3") -> str:
    r = requests.get(url, timeout=120)
    r.raise_for_status()
    with open(path, "wb") as f:
        f.write(r.content)
    return path

if __name__ == "__main__":
    task_id = create_task()
    print(f"submitted: {task_id}")
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    print(f"done, downloading: {url}")
    print(f"saved to {download(url)}")

python3 make_song.py로 실행하세요. 스크립트는 작업을 제출하고 5초마다 폴링하며, 완료된 트랙을 로컬에 저장합니다.

프로덕션 환경 패턴

폴링 대신 콜백 사용

간단한 스크립트 범위를 넘어서는 모든 용도에서는 콜백을 등록하여 작업이 종료 상태에 도달할 때 hiapi가 결과를 푸시하도록 하세요. 최상위 callback 객체를 추가합니다(model과 같은 레벨이며 input 내부가 아님):

{
  "model": "minimax-music-1.5",
  "input": {"prompt": "...", "lyrics": "..."},
  "callback": {"url": "https://your.domain.example/hiapi/callback", "when": "final"}
}

"when": "final"만 지원됩니다. 작업이 성공하거나 실패할 때 증분 진행 이벤트가 아니라 POST 한 번을 받습니다. 폴링은 개발과 일회성 작업에 적합하고, 대량의 트랙을 생성하거나 대기열 뒤에서 실행할 때는 콜백이 더 낫습니다. 열린 루프를 유지할 필요가 없고, 잦은 폴링으로 인한 속도 제한도 피할 수 있기 때문입니다. 콜백이 도착하지 않는다면 hiapi 작업 콜백이 발생하지 않는 이유의 점검 목록을 따라 확인하세요.

멱등성과 재시도

작업 생성 자체는 멱등적이지 않습니다. 타임아웃된 POST /v1/tasks를 재시도하면 작업이 두 개 생성될 수 있고(비용도 두 번 발생), 생성 호출이 반환되자마자 taskId를 영속화한 뒤 재시작 시 해당 id를 폴링하여 복구하세요. 무작정 다시 제출하지 마세요. 작업이 멈춘 것처럼 보여도 즉시 종료하고 다시 생성하지 말고 hiapi /v1/tasks 작업이 멈추거나 타임아웃될 때를 참고하여 느린 작업과 죽은 작업을 구분하는 방법을 확인하세요.

오류 처리

두 가지 실패 유형은 다르게 나타납니다:

요청 수준 오류는 동기적으로 반환됩니다. 잘못되었거나 권한이 없는 키는 permission_denied 오류("This API key cannot use the selected model...")와 함께 지원 팀에 제시할 수 있는 request_id를 반환합니다. 스키마 위반은 400 INVALID_REQUEST와 prompt: minLength: got 1, want 10 같은 정확한 메시지를 반환합니다.
작업 수준 실패는 폴링/콜백 결과에서 status: "fail"로 나타나며 error.code와 error.message를 포함합니다. 생성 호출은 성공했지만 생성은 실패한 경우입니다. 이런 실패가 재시도 로직에 들어가야 합니다.

제출 전에 클라이언트에서 길이를 검증하세요. prompt는 최대 300자, lyrics는 최대 600자이며, API는 초과 입력을 잘라내지 않고 거부합니다.

가격 및 제한

MiniMax Music 1.5는 생성된 트랙 단위로 과금되며 사용량 기반 가격을 적용합니다. 현재 요금은 hiapi 가격 페이지와 minimax-music-1.5 모델 페이지에서 확인하세요. 모델 페이지에서는 코드를 작성하기 전에 playground에서 모델을 먼저 사용해 볼 수 있습니다.

자주 묻는 질문

minimax-music-1.5는 어떤 입력 필드를 허용하나요?

정확히 네 가지입니다. prompt(필수, 10–300자), lyrics(필수, 10–600자), sample_rate(선택, 16000/24000/32000/44100), bitrate(선택, 32000/64000/128000/256000). 그 외의 필드는 additional properties not allowed로 거부됩니다.

곡 구조를 제어할 수 있나요?

네. lyrics에서 [Verse], [Chorus] 같은 섹션 태그로 구조를 조직하세요. 모델은 이 태그를 활용해 편곡을 형성합니다. 태그를 포함한 전체 가사 문자열은 600자 제한 내에 있어야 합니다.

순수 기악 음악을 생성할 수 있나요?

입력 스키마에 기악 전환은 없습니다. 이 엔드포인트는 가사로 구동되므로 prompt에서 원하는 악기 편성과 분위기를 설명하세요. 순수 기악 사용 사례는 모델 페이지에서 현재 기능 목록을 확인하세요.

오디오 파일은 어떻게 받나요?

작업 상태가 success일 때 data.output[0].url에 다운로드 링크가 저장되어 있습니다. 즉시 가져와 직접 바이트를 저장하세요. 출력 URL은 만료됩니다.

폴링과 콜백 중 무엇을 사용해야 하나요?

개발과 단일 작업에는 폴링을 사용하세요(5초 간격이면 충분). 프로덕션에서는 when: "final"이 포함된 callback을 사용하여 연결을 열어 두지 마세요. 특히 대량으로 트랙을 생성할 때 중요합니다.

permission_denied가 반환되는 이유는 무엇인가요?

키가 유효하지 않거나 해당 모델에 접근 권한이 없습니다. 대시보드에서 키를 검증하고 Authorization: Bearer sk-... 형식으로 전송했는지 확인하세요.

태그튜토리얼 음악 생성 MiniMax hiapi api

모든 아티클 보기 →