블로그

튜토리얼

minimax-music-1.5 API 튜토리얼: curl과 Python Requests

Nov 12, 2026
커버 이미지: 따뜻한 차콜 배경 위로 넓은 호박색 빛 띠가 좁은 틈을 비스듬히 가로지르고, 은은한 어두운 기하학 블록이 더해져 절제된 여백의 구도를 이룹니다.
이 페이지에서

minimax-music-1.5의 요청 요구 사항

첫 줄의 코드를 작성하기 전에 음악 생성 호출이 정확히 무엇으로 구성되는지 파악하는 것이 좋습니다. 텍스트 완성과 달리 음악 요청에는 각자 역할이 다른 두 가지 창작 입력과 출력을 형성하는 여러 제어 항목이 있습니다.

높은 수준에서 보면 minimax-music-1.5 요청은 다음을 포함합니다:

  • 스타일 또는 프롬프트 설명 —— 음악 방향: 장르, 분위기, 악기 편성, 속도감, 제작 특성.
  • 가사 —— 트랙에 보컬이 있을 때 실제로 노래할 텍스트. 순수 기악 요청은 비워 두거나 이 항목을 생략합니다.
  • 구조 제어 —— 예를 들어 생성 트랙의 목표 길이로, 모델이 작곡할 길이를 제한합니다.
  • 모델 식별자 —— minimax-music-1.5 —— 게이트웨이가 작업을 올바른 백엔드로 라우팅하도록 합니다.

기억할 멘탈 모델: 스타일 입력은 모델에게 어떻게 들려야 하는지를 알려주고, 가사 입력은 모델에게 무엇을 노래하는지를 알려줍니다. 둘은 서로 바꿔 쓸 수 없습니다. 장르 설명을 가사 필드에 넣으면 혼란스러운 출력을 얻게 되고, 가사를 비워 둔 채 보컬 트랙을 요청하면 모델이 스스로 만들어 내야 합니다. 시작하기 전에 두 모드 중 어느 쪽인지 먼저 정하세요.

코드를 작성하기 전에 내면화해야 할 두 가지가 더 있습니다:

  1. 음악 생성은 즉각적이지 않습니다. 완성된 트랙을 생성하려면 실제 계산 시간이 필요하므로 이 API는 설계상 비동기입니다. 작업을 제출한 다음 결과를 가져옵니다. 한 번의 블로킹 호출만 보여주는 튜토리얼은 폴링 루프를 숨기고 있는 것입니다.
  2. 출력은 참조로 전달됩니다. 인라인 원시 바이트가 아니라 생성된 오디오의 URL을 받습니다. 별도로 다운로드하거나 스트리밍해야 합니다.

이 세 가지——스타일과 가사의 구분, 비동기 수명 주기, URL 기반 출력——를 명확히 설명할 수 있으면 실제 요청 본문은 쉽게 읽힙니다.

HiAPI에서 초기 설정 완료하기

첫 호출 전에 세 가지가 필요합니다: API 키, 기본 엔드포인트 주소, 그리고 키를 하드코딩하지 않는 습관.

API 키

HiAPI 계정 콘솔에서 키를 생성하세요. 비밀번호처럼 다루세요: 모든 요청을 인증하고 계정 사용량과 연결됩니다. 버전 관리에 커밋하지 말고, 공개 gist에 붙여넣지 말고, 모바일이나 브라우저 번들에 패키징하지 마세요.

기본 엔드포인트 주소

모든 호출은 단일 통합 인터페이스 뒤에서 minimax-music-1.5를 노출하는 HiAPI 게이트웨이로 전송됩니다. 모델마다 별도의 자격 증명이나 SDK가 필요하지 않습니다——요청 본문의 모델 이름이 백엔드를 선택합니다. 정확한 기본 URL과 현재 요청 경로는 API 참조 문서를 확인하세요.

소스에서 키 분리하기

임시 스크립트부터 프로덕션 환경까지 모두 적용되는 패턴은 환경 변수입니다:

export HIAPI_API_KEY="your-key-here"

그런 다음 런타임에 읽습니다. Python에서는 os.environ["HIAPI_API_KEY"], 셸에서는 $HIAPI_API_KEY입니다. 로컬에서 .env 파일을 사용한다면 첫 커밋전에 .gitignore에 추가하세요——나중이 아니라. 배포된 서비스의 경우 플랫폼의 시크릿 관리자를 통해 키를 주입하고 이미지에 넣지 마세요.

무언가를 만들기 전에 빠른 확인을 하세요: 곧 실행할 프로세스가 키를 볼 수 있는지 확인하세요(같은 셸에서 echo $HIAPI_API_KEY 실행). 대부분의 "인증 실패" 보고는 한 터미널에서 키를 내보내고 다른 터미널에서 스크립트를 실행한 데서 비롯됩니다.

curl로 첫 번째 동작하는 요청 보내기

curl부터 시작하세요. 모든 추상화 계층을 벗겨내고 네트워크에서 실제로 전송되는 내용을 정확히 볼 수 있습니다. 아래 요청은 짧은 보컬 트랙을 생성합니다. 필드 값을 자신의 의도에 맞게 조정하세요.

curl -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-1.5",
    "prompt": "따뜻한 인디 포크, 핑거스타일 어쿠스틱 기타, 부드러운 브러시 드럼, 친밀한 근접 보컬",
    "lyrics": "[verse]\n아침 햇살이 부엌 바닥에 내려앉아\n[chorus]\n우리는 아직 여기 있어, 우리는 아직 여기 있어",
    "duration": 30
  }'

줄별 설명:

  • -X POST —— 생성은 생성 작업이지 읽기 작업이 아닙니다.
  • Authorization: Bearer $HIAPI_API_KEY —— 이전 섹션의 키로, 셸이 확장하므로 변수를 참조하는 한 기록에 나타나지 않습니다.
  • Content-Type: application/json —— 게이트웨이는 JSON을 기대합니다. 이 헤더를 생략하면 혼란스러운 4xx 응답의 흔한 원인이 됩니다.
  • model —— 요청을 minimax-music-1.5에 고정합니다.
  • prompt —— 스타일 설명. 형용사 하나만 쓰지 말고 악기 편성과 분위기를 구체적으로 설명하세요.
  • lyrics —— 노래 텍스트로, [verse]와 [chorus] 같은 가벼운 섹션 태그로 구조를 힌트합니다. \n 이스케이프는 JSON 개행입니다.
  • duration —— 생성 트랙의 길이를 초 단위로 제한합니다.

반환되는 것은 오디오가 아니라 작업 참조입니다. 그것을 캡처하세요:

curl -s -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | tee job.json

-d @payload.json으로 파일에서 요청 본문을 읽으면 셸 기록을 깨끗하게 유지하고 Python으로의 전환이 간단해집니다——그 파일이 바로 요청 본문입니다. 응답을 검사하고 작업 또는 task 식별자와 상태 필드를 기록하세요. 결과를 가져오려면 그 식별자가 필요합니다.

요청을 Python으로 이식하기

Python 버전은 재작성이 아니라 curl 호출의 전사처럼 느껴져야 합니다. requests를 사용하고, 환경 변수에서 키를 읽고, 요청 본문을 읽기 쉽게 딕셔너리로 유지하세요.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "minimax-music-1.5",
    "prompt": "따뜻한 인디 포크, 핑거스타일 어쿠스틱 기타, 부드러운 브러시 드럼, 친밀한 근접 보컬",
    "lyrics": "[verse]\n아침 햇살이 부엌 바닥에 내려앉아\n[chorus]\n우리는 아직 여기 있어, 우리는 아직 여기 있어",
    "duration": 30,
}

response = requests.post(
    f"{BASE_URL}/minimax-music-1.5",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    data=json.dumps(payload),
    timeout=60,
)
response.raise_for_status()
job = response.json()
print(json.dumps(job, indent=2))

예상치 못한 일을 피하기 위한 이식 팁:

  • data=와 함께 json.dumps를 사용하거나 json=payload를 사용하세요. 둘 다 작동하며, json=payload는 requests가 콘텐츠 타입을 대신 설정하게 합니다. 직렬화하지 않고 딕셔너리를 data=에 직접 전달하면 서버는 폼 인코딩된 요청 본문을 받고 거부합니다.
  • 항상 timeout을 설정하세요. 설정하지 않으면 정체된 연결이 프로세스를 무기한 멈추게 합니다. 이 타임아웃은 제출을 다루며 생성은 다루지 않는다는 점을 기억하세요——그것은 다음 섹션에서 다룹니다.
  • 파싱 전에 raise_for_status()를 호출하세요. 4xx 또는 5xx를 깔끔한 예외로 바꿔, 존재하지 않는 필드에 접근할 때 수수께끼 같은 KeyError가 발생하지 않게 합니다.
  • 응답 객체를 보관하세요. 디버깅 시 response.status_code와 response.text를 출력하면 파싱된 오류보다 훨씬 많은 정보를 알 수 있습니다.

이 스크립트의 결과는 curl이 생성한 것과 동일한 작업 참조입니다. 제출 이후의 모든 것——폴링, 재시도, 다운로드——은 어떤 언어를 쓰든 완전히 동일하며, 바로 그래서 별도 섹션으로 다룰 가치가 있습니다.

비동기 작업 수명 주기 처리하기

음악 생성에서 가장 흔한 실수는 채팅 완성처럼 다루는 것입니다: 보내고, 기다리고, 트랙을 읽기. 제출 호출은 빠르게 반환되지만 오디오는 아직 존재하지 않습니다. 코드는 반드시 루프를 닫아야 합니다.

세 가지 상태

모든 작업은 작은 상태 머신을 거칩니다:

  1. 제출됨(Submitted) —— 작업 식별자를 받았고, 작업이 대기 중이거나 실행 중입니다.
  2. 완료됨(Finished) —— 오디오가 준비되었고 응답에 이를 가리키는 URL이 있습니다.
  3. 실패함(Failed) —— 생성이 중단되었고 응답이 이유를 설명합니다.

폴링 루프는 세 상태를 모두 구분해야 합니다. 상태가 submitted이면 계속 기다리라는 뜻이지 재시도하라는 뜻이 아닙니다.

폴링하되 과도하게 요청하지 마세요

CPU가 허용하는 가장 빠른 속도로 상태 확인을 보내는 순진한 루프는 속도 제한을 소모하면서 새로운 정보를 주지 않습니다——트랙을 렌더링하는 데 수십 초가 걸리므로 분당 수백 번의 확인은 순수한 낭비입니다. 백오프를 추가하세요:

import time

def wait_for_job(job_id, base_url, api_key, interval=2.0, max_wait=300):
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(
            f"{base_url}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "finished":
            return data
        if status == "failed":
            raise RuntimeError(f"job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} not finished after {max_wait}s")

정확한 폴링 경로와 상태 문자열은 API 참조 문서를 확인하세요——위의 이름은 예시로 간주하고 문서의 값에 맞추세요.

올바른 대상 재시도하기

재시도는 두 개의 서로 다른 계층에 속하며, 둘을 혼동하면 중복 작업이 발생합니다.전송 재시도——HTTP 호출 자체가 5xx 또는 연결 재설정으로 실패하는 경우——는 폴링 요청에 대해 안전하게 반복할 수 있습니다.생성 재시도는 새로운 제출로 렌더링을 한 번 더 소비하므로, 작업이 명확히 실패를 보고할 때만 하고 횟수를 제한하세요. 폴링이 느리다고 해서 제출을 재시도하지 마세요.

마지막으로, 작업 식별자를 받는 즉시 저장하세요. 프로세스가 제출과 완료 사이에 충돌하면, 그 식별자는 비용을 다시 지불하지 않고 완료된 트랙을 복구하는 유일한 방법입니다.

가사, 스타일, 길이 입력 조정하기

minimax-music-1.5에서 쓸 만한 트랙을 얻는 것은 주로 두 텍스트 필드를 의식적으로 작성하는 데 달려 있습니다. 몇 가지 습관이 출력이 평범한지 아니면 실제로 공개하고 싶은 것인지를 결정합니다.

스타일 프롬프트를 프로듀서의 브리프처럼 작성하기

장르 단어 하나는 모델에게 너무 많은 자유를 줍니다. 구체적인 차원을 쌓으세요:

  • 장르와 시대 —— "90년대 후반 트립합"이 "일렉트로닉"보다 낫습니다.
  • 악기 편성 —— 주도 악기와 리듬 섹션을 명시하세요.
  • 분위기와 에너지 —— "우울하지만 추진력 있는"은 형용사 하나로 표현할 수 없는 긴장을 만들어 냅니다.
  • 제작 특성 —— "로파이, 테이프 새추레이션, 넓은 스테레오"가 믹스를 이끕니다.

한두 문장으로 유지하세요. 장문 단락형 프롬프트는 정교하게 만드는 대신 희석시키는 경향이 있습니다.

태그로 가사 구조 구성하기

가벼운 섹션 마커——[verse], [chorus], [bridge]——는 모델에게 로드맵을 주고, 보통 태그 없는 통짜 텍스트보다 더 명확한 곡 구조를 만듭니다. 각 줄은 노래할 수 있을 만큼 짧게 유지하세요. 한 줄에 열두 단어는 멜로디에 거의 맞지 않습니다. 기악 트랙의 경우, 스타일 텍스트가 든 빈 문자열을 보내지 말고 lyrics를 완전히 생략하세요.

길이를 소재에 맞추기

길이는 작곡을 제한합니다. 완전한 verse-chorus-verse 가사에 짧은 길이는 압축을 강요해 결과가 급하게 들리고, 두 줄 가사에 긴 길이는 반복을 초래합니다. 먼저 곡의 형태를 결정하고 그에 맞는 길이를 설정하세요. 더 긴 작품이 필요하면 길이를 늘려 잘 되기를 기대하지 말고 가사를 확장하세요.

작은 변경으로 반복하기

트랙이 거의 맞지만 아닐 때는 한 번에 하나의 입력만 바꾸세요——프롬프트의 악기 편성, 또는 속도 단어, 또는 잘 맞지 않는 가사 한 줄. 모든 것을 동시에 바꾸면 어느 필드가 개선을 가져왔는지 알 수 없습니다. 가장 좋은 요청 본문은 파일에 저장하고 거기서 분기하세요.

흔한 오류 문제 해결하기

대부분의 실패는 인식 가능한 몇 가지 범주에 속합니다. 증상을 맞추고, 수정을 적용하고, 계속 나아가세요.

인증 실패

증상: 401 또는 403, 자격 증명 관련 메시지.

  • 헤더가 Authorization: Bearer <key>인지 확인하세요——Bearer 단어와 공백이 모두 필요합니다.
  • 환경 변수가 요청을 보내는 프로세스에 실제로 설정되었는지 확인하세요. 한 셸에서 내보낸 키는 cron 작업이나 Docker 컨테이너에 도달하지 않습니다.
  • 키와 함께 복사된 불필요한 공백이나 개행을 확인하세요.

형식이 잘못된 요청 본문

증상: 유효성 검사 메시지와 함께 400.

  • Content-Type: application/json을 보내세요. 이 헤더가 없으면 서버가 완전히 올바른 본문을 오해합니다.
  • requests를 사용한다면 json=payload 또는 data=json.dumps(payload)를 전달하세요. 원시 딕셔너리를 data=에 전달하면 폼 인코딩됩니다.
  • API 참조 문서와 필드 이름과 타입을 검증하세요: model은 정확히 minimax-music-1.5여야 하고, duration은 정수이며, 가사 개행은 JSON에서 \n으로 올바르게 이스케이프되어야 합니다.
  • 확실하지 않을 때는 Python이 개입하기 전에 curl -d @payload.json으로 요청 본문 자체의 유효성을 먼저 분리해 판단하세요.

타임아웃과 연결 오류

증상: 요청이 멈추거나 연결 오류가 발생합니다.

  • 모든 호출에 명시적 timeout을 설정하세요. 제출 타임아웃은 대기열 지연을 덮을 만큼 충분히 넉넉해야 하지만 렌더링 시간은 아닙니다.
  • 폴링 타임아웃을 전체 max_wait와 같게 설정하지 마세요. 단일한 느린 상태 확인이 아직 실행 중인 작업을 중단시켜서는 안 됩니다.
  • 제출이 반복적으로 타임아웃되지만 폴링은 성공한다면 요청 본문이 너무 클 수 있습니다——가사를 줄이세요.

폴링 오류

증상: 계속 폴링해도 finished를 볼 수 없거나 잘못된 리소스를 폴링합니다.

  • 요청 ID나 연관 헤더가 아니라 제출 응답의 작업 식별자를 사용하고 있는지 확인하세요.
  • submitted/running을 "재시도 제출"이 아니라 "계속 기다리기"로 취급하세요. 반복 제출은 두 번째 트랙을 생성합니다.
  • 백오프를 추가하세요. 공격적인 폴링은 속도 제한을 유발하며, 이는 실패처럼 보이지만 스스로 만든 것입니다.
  • 작업이 failed를 보고하면 재제출 전에 메시지를 읽으세요——잘못된 가사 태그나 범위를 벗어난 길이는 매번 같은 방식으로 실패합니다.

막혔을 때는 원시 curl 호출에 -v를 붙여 실제 상태 줄과 헤더를 확인하세요. 이 단계는 어떤 양의 Python 디버깅보다 빠르게 대부분의 모호함을 해소합니다.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기