튜토리얼

HiAPI API를 통해 mureka-9.5/instrumental을 사용하는 방법: curl 및 Python 가이드

Nov 3, 2026

HiAPI에서 mureka-9.5/instrumental의 기능

mureka-9.5/instrumental은 HiAPI의 텍스트-음악 생성 엔드포인트로, 순수 기악 출력에 특화되어 튜닝되었습니다—배경 음악, 루프 구간, 깔개 음악, 사운드트랙. 프롬프트로 곡을 설명하고 단일 작업을 제출하면 HiAPI가 완성된 오디오 리소스를 반환하며, 게임, 영상 편집, 팟캐스트 또는 제품 데모에 다운로드하여 넣을 수 있습니다.

instrumental(기악)이라는 단어가 핵심입니다. 이 엔드포인트는 주창 보컬 공연이 없는 음악을 대상으로 하므로 내레이션이나 대사가 명료하게 들려야 하는 장면에 적합합니다. 가사가 있는 노래가 필요하다면それは 다른 문제이고, 나레이션 아래에 깨끗한 배경 음악을 깔고 싶다면 이것이 올바른 도구입니다.

다음 경우에 이 엔드포인트를 선택하세요:

음악 라이브러리에서 가져오는 대신 생성된 배경 음악(BGM)을 원할 때.
한 번의 맞춤 의뢰 대신 빠르고 프로그래밍 방식으로 많은 변형을 생성해야 할 때.
파이프라인이 이미 HTTP를 사용 중이며 음악을 다른 리소스 생성 단계처럼 처리하고 싶을 때.
예측 가능한 요청 형태(제출, 폴링, 다운로드)를 중시할 때.

다른 음악 생성 엔드포인트와 마찬가지로 작업은 비동기입니다. 제출 후 작업이 반환되며, 오디오가 생성될 때까지 추적해야 합니다. 처음부터 이를 중심으로 코드를 설계하면 나머지 통합 작업은 일상적인 일이 됩니다.

제품에서의 적용 위치

전형적인 사용자는 필요에 따라 곡이 필요한 콘텐츠 파이프라인입니다: 각 클립 아래에 음악을 깔고 싶은 영상 렌더러, 환경 루프 구간을 원하는 게임, 또는 사용자가 분위기를 입력하고 결과를 듣는 프로토타이핑 도구. 이 엔드포인트는 텍스트 기반이므로 이미 가진 메타데이터—장르, 리듬감, 분위기, 예상 길이—로 프롬프트를 템플릿화하여 렌더링 시 생성할 수 있습니다.

각 요청을 자체 수명 주기를 가진 생성 작업으로 취급하세요. 이 틀은 재시도 로직, 로깅, 비용 산정을 합리적으로 유지해줍니다.

요청을 보내기 전 준비

첫 호출이 성공하기 전에 충족해야 할 몇 가지 조건이 있습니다. 어느 것도 복잡하지 않지만, 하나라도 빠뜨리면 첫 요청 실패의 가장 흔한 원인이 됩니다.

자격 증명

HiAPI API 키가 필요합니다. 기밀처럼 다루세요: HIAPI_API_KEY 같은 환경 변수에서 로드하고, 제출하는 스크립트에 절대 하드코딩하지 말며, 유출되면 교체하세요. 키는 Authorization 헤더를 통해 베어러 토큰으로 전송됩니다.

export HIAPI_API_KEY="your_api_key_here"

엔드포인트와 전송

HiAPI 통합 API를 통해 mureka-9.5/instrumental 모델을 호출합니다. 기본 URL은 HiAPI API 호스트이며, 모델 식별자는 HiAPI가 이 엔드포인트에 문서화한 관례에 따라 요청 페이로드 또는 경로에 넣습니다. HTTPS를 사용하고, Content-Type: application/json을 보내며, JSON 본문을 전송하세요.

매개변수 이름을 추측하지 마세요. HiAPI는 이 모델이 허용하는 필드를 문서화했습니다; 그 집합 밖의 것은 최선의 경우 무시되고 최악의 경우 거부됩니다. 원하는 필드가 문서화되지 않았다면 계약의 일부가 아닙니다—존재하는 것을 중심으로 구축하세요.

준비해야 할 것

음악을 설명하는 프롬프트: 장르, 악기 편성, 분위기, 리듬감, 용도.
모델이 공개한 문서화된 길이 또는 변형 옵션.
작업 식별자를 저장하고 나중에 다운로드 URL을 저장할 위치.
코드 실행 위치에서 HiAPI 호스트로의 네트워크 접근.

시간에 관한 참고

생성은 즉각적이지 않습니다. 클라이언트 타임아웃을 넉넉히 설정하고 폴링이 필요할 것으로 예상하세요. 동기적 사고—요청을 보내고 같은 응답에서 오디오가 반환될 때까지 차단—는 불안정한 코드로 이어집니다.

사용 가능한 curl 요청

curl부터 시작하세요. 당신과 HTTP 대화 사이의 모든 계층을 제거하므로 문제가 있으면 즉시 볼 수 있습니다.

호출

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mureka-9.5/instrumental",
    "input": {
      "prompt": "warm lo-fi hip hop instrumental, mellow electric piano, soft vinyl crackle, relaxed 80 bpm, no vocals"
    }
  }'

먼저 두 환경 변수를 설정하여 선택한 내용 외에 민감한 정보가 셸 기록에 평문으로 남지 않도록 하세요:

export HIAPI_BASE_URL="https://api.hiapi.ai/v1/..."   # 이 엔드포인트의 문서화된 경로 사용
export HIAPI_API_KEY="your_api_key_here"

각 부분의 역할

-X POST — 제출은 생성 작업입니다.
-H "Authorization: Bearer ..." — 계정으로 호출을 인증합니다.
-H "Content-Type: application/json" — 서버에 본문이 JSON임을 알립니다; 생략하면 많은 서버가 본문을 그대로 거부합니다.
-d '{...}' — JSON 페이로드. model 필드는 엔드포인트를 지정하고; input 객체는 프롬프트와 기타 문서화된 필드를 담습니다.
-sS — 진행은 숨기되 오류는 표시. 스크립트에서 유용합니다.

응답 읽기

응답은 JSON입니다. 작업 또는 작업 식별자와 상태 필드를 찾으세요. 확인하기 위해 예쁘게 출력하세요:

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | jq .

식별자를 보관하세요. 이후 모든 상태 확인의 핸들입니다. 전체 응답 본문을 앱에 파싱하지 말고; 작업 ID와 상태를 추출하고 디버깅을 위해 원본 응답을 저장하세요.

2xx가 아닌 상태를 받으면 본문을 읽으세요—HiAPI는 구조화된 오류 메시지를 반환하며, 보통 문제가 된 필드를 지적합니다.

Python의 동일한 요청

Python 버전은 curl 호출과 완전히 대응합니다: 같은 헤더, 같은 JSON 본문. 간결함을 위해 requests를 사용하거나, 의존성이 전혀 없다면 표준 라이브러리를 사용하세요.

requests 사용

import os
import requests

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

payload = {
    "model": "mureka-9.5/instrumental",
    "input": {
        "prompt": (
            "warm lo-fi hip hop instrumental, mellow electric piano, "
            "soft vinyl crackle, relaxed 80 bpm, no vocals"
        )
    },
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

resp = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
job_id = data["id"]          # 문서화된 필드 이름 사용
print("submitted:", job_id, data.get("status"))

표준 라이브러리 사용

의존성을 추가할 수 없다면:

import json, os, urllib.request

req = urllib.request.Request(
    os.environ["HIAPI_BASE_URL"],
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(req, timeout=30) as r:
    data = json.load(r)

실용적 습관

timeout=30은 제출 시에만 사용하세요. 폴링은 자체 루프와 타임아웃이 필요합니다.
파싱 전에 raise_for_status()를 호출하세요. 오류 응답 본문은 작업이 아닙니다.
작업 ID 추출을 작은 도우미 함수로 감싸 필드 이름 변경 시 한 줄만 수정하면 되게 하세요.
API 키를 절대 로깅하지 마세요; 대신 작업 ID와 상태를 로깅하세요.
페이로드를 코드의 딕셔너리로 유지하고 한 번만 직렬화하여 테스트가 이에 대해 단언할 수 있게 하세요.

비동기 작업 처리와 폴링

제출은 첫 단계입니다. 생성은 서버 측에서 진행되어 나중에 완료되므로, 작업이 종료 상태를 보고할 때까지 상태 엔드포인트를 폴링합니다.

루프 형태

작업을 제출하고 ID를 캡처합니다.
잠시 대기합니다.
해당 ID의 상태를 조회합니다.
상태가 대기 중 또는 처리 중이면 백오프 후 반복합니다.
상태가 성공이면 출력을 읽습니다.
상태가 실패이면 오류를 기록하고 중단하세요—맹목적으로 재시도하지 마세요.

신뢰할 수 있는 구현

import time, random, requests

def wait_for_job(job_id, base_status_url, headers,
                 timeout_s=600, initial_delay=2.0, max_delay=30.0):
    deadline = time.monotonic() + timeout_s
    delay = initial_delay

    while time.monotonic() < deadline:
        r = requests.get(f"{base_status_url}/{job_id}", headers=headers, timeout=30)
        r.raise_for_status()
        status = r.json()["status"]

        if status in ("succeeded", "completed", "success"):
            return r.json()
        if status in ("failed", "error", "cancelled"):
            raise RuntimeError(f"job {job_id} ended as {status}: {r.text}")

        time.sleep(delay + random.uniform(0, 0.5))   # jitter
        delay = min(delay * 1.5, max_delay)          # exponential backoff

    raise TimeoutError(f"job {job_id} did not finish in {timeout_s}s")

각 세부 사항이 중요한 이유

지터(Jitter)는 여러 작업이 병렬로 실행될 때 동기화된 재시도를 방지합니다.
백오프(Backoff)는 곡이 렌더링되는 동안 상태 엔드포인트를 두드리는 것을 방지합니다.
마감 시간(Deadline)은 무한 대기를 파이프라인이 처리할 수 있는 깔끔한 예외로 전환합니다.
종료 상태 확인은 HiAPI 문서화된 상태 문자열과 일치해야 합니다. 추측을 믿지 말고 API 참조로 확인하세요.
재시도는 일시적 네트워크 오류(타임아웃, 5xx)를 중심으로 해야 하며, 유효성 검사 오류로 이미 실패한 작업을 중심으로 해서는 안 됩니다.

운영 팁

폴링을 시작하기 전에 job_id를 영속화하세요. 프로세스가 죽으면 두 번째 생성 비용을 지불하는 대신 폴링을 재개할 수 있습니다. 타임스탬프가 있는 상태 전환을 기록하여 시간이 어디에 쓰이는지 볼 수 있게 하세요. 많은 작업을 실행한다면 각 작업에 요청 스레드를 차단하는 대신 큐를 통해 소수의 작업을 병렬로 폴링하세요.

기악 출력 가져오기 및 다운로드

기악 모드는 요청을 통해 표현되며, 엔드포인트는 그러한 출력에 특화되어 있습니다. 실제로는 프롬프트 문구가 이를 강화합니다: 악기를 명명하고, 분위기를 설명하며, 보컬이 없음을 선언하세요. 보컬 라인을 요구하는 프롬프트는 엔드포인트의 목적과 충돌합니다.

오디오가 나타나는 위치

작업이 성공 상태에 도달하면 상태 응답이 결과를 담습니다. 오디오는 상태 JSON의 base64가 아닌 별도로 가져오는 URL로 전달될 것으로 예상하세요. 응답을 읽고 문서화된 출력 필드에서 다운로드 URL을 추출하세요.

result = wait_for_job(job_id, status_url, headers)
# 처음 몇 번은 결과를 주의 깊게 확인한 후 해당 필드를 고정하세요.
audio_url = result["output"]["audio_url"]   # API 참조에서 필드 이름 확인

with requests.get(audio_url, stream=True, timeout=60) as r:
    r.raise_for_status()
    with open(f"{job_id}.mp3", "wb") as f:
        for chunk in r.iter_content(chunk_size=65536):
            f.write(chunk)

다운로드 습관

스트리밍으로 디스크에 쓰세요. 음악 파일은 큽니다; 전체를 메모리에 로드하는 것은 피해야 할 부담입니다.
콘텐츠 유형을 확인하세요. 하드코딩된 확장자가 아닌 응답이 암시하는 확장자로 파일을 저장하세요.
URL을 임시로 취급하세요. 적시에 다운로드하거나 문서에서 안정적이라고 명시한 경우에만 URL을 영속화하세요. 영구 보존을 위해 바이트를 자체 스토리지에 복사하세요.
한 번만 가져오세요. 완료 표시 없이 재시도 루프에서 다운로드하면 부분 파일이 쉽게 생깁니다. 임시 이름으로 쓰고 성공 후 이름을 변경하세요.
출처를 기록하세요. 작업 ID와 프롬프트를 파일과 함께 저장하세요. 나중에 변형이 필요할 때 정확한 입력을 갖게 됩니다.

흔한 실패 지점과 수정

대부분의 첫 통합 문제는 짧은 목록에 속합니다. 다음은 점검 목록입니다.

401 / 403 — 인증. 헤더가 잘못되었거나, 키가 없거나, 환경 변수가 빈 문자열로 해석됩니다. 키가 코드를 실행하는 동일한 셸 또는 프로세스에 설정되어 있고 헤더가 정확히 Authorization: Bearer <key>로 읽히는지 확인하세요.

400 — 페이로드 형식 오류. model 누락, mureka-9.5/instrumental의 오타, 잘못된 JSON, 또는 엔드포인트가 허용하지 않는 필드. 먼저 curl로 본문을 보내 페이로드를 코드와 분리하세요. 보내기 전에 JSON을 검증하세요; 후행 쉼표가 고전적인 문제입니다.

415 또는 빈 본문 오류 — 콘텐츠 유형. Content-Type: application/json이 반드시 존재해야 합니다. 일부 HTTP 클라이언트는 json=을 전달할 때 자동으로 설정하지만, 모든 클라이언트가 그렇지는 않습니다.

폴링 타임아웃. 마감 시간이 너무 짧거나, 백오프가 너무 공격적이거나, 작업이 실제로 실패했는데 여전히 실행 중으로 분류한 것입니다. 문서와 정확한 상태 문자열을 확인하고 디버깅 시 각 상태 전환을 출력하세요.

다운로드 URL 누락. 잘못된 필드를 읽었거나, 작업이 종료 성공 상태에 도달하기 전에 응답을 읽었습니다. 성공 페이로드를 한 번 전체 기록하여 오디오 URL 경로를 확인한 후 고정하세요.

중복 생성. 폴러가 충돌하여 무언가가 다시 제출했습니다. 폴링 전에 작업 ID를 영속화하고, 새 작업을 제출하기 전에 기존 작업을 확인하세요.

속도 제한. 429 응답에 지터를 두고 백오프하며, 많은 스레드에서 동시에 폭발하는 대신 작업을 큐에 넣으세요.

이 순서대로 처리하세요—인증, 페이로드, 콘텐츠 유형, 폴링, 출력—그러면 보통 한 번에 원인을 찾을 수 있습니다. curl 호출과 그 Python 쌍둥이 버전이 모두 엔드투엔드로 성공하면, 엔드포인트는 요청한 일을 하고 있습니다: 프롬프트를 기악 곡으로 전환하고 다운로드 URL을 건네줍니다.

모든 아티클 보기 →