튜토리얼

HiAPI의 ElevenLabs Music API: curl, Python 및 프롬프트 레시피로 음악 생성하기

HiAPI를 통해 elevenlabs/music-v2.5를 호출하는 실전 튜토리얼과 스타일·분위기·길이를 위한 복사 가능한 프롬프트 레시피

Nov 12, 2026

이 페이지에서

HiAPI를 통해 elevenlabs/music-v2.5를 호출하는 이유

제품에 음악 생성 기능을 추가하려면, 가장 빠른 경로가 가장 깔끔한 경로인 경우는 드뭅니다. 백엔드를 모델 제공자에 직접 연결한다는 것은 해당 제공자의 계정 설정, 인증 방식, 재시도 의미론, 요청 구조를 직접 책임져야 한다는 뜻입니다. 새 모델을 하나 도입할 때마다 이런 결정 묶음이 하나씩 늘어나고, 실험할 때마다 통합 브랜치가 하나씩 남습니다.

HiAPI를 통해 elevenlabs/music-v2.5를 호출하면 이 작업의 형태가 달라집니다. 기본 URL 하나, 인증 헤더 하나, 그리고 모델 간에 전환해도 안정적으로 유지되는 요청 규약 한 세트만 있으면 됩니다. 모델 식별자(elevenlabs/music-v2.5)는 요청 본문 안의 문자열일 뿐이므로, 음악 모델 간에 전환하거나 비교를 위해 두 번째 모델을 시험해 볼 때 새 SDK를 가져올 필요 없이 한 줄만 바꾸면 됩니다.

통합 방식을 선택하는 개발자에게 주목할 만한 세 가지 실질적 이점이 있습니다:

통합된 자격 증명 관리 지점. 키 관리, 교체, 환경 분리(개발/스테이징/프로덕션)가 제공자별로 늘어나지 않고 한곳에 집중됩니다.
이식 가능한 요청 패턴. 아래 curl 및 Python 코드 조각은 HiAPI에서 다른 모델을 사용할 때와 동일합니다. 패턴을 한 번만 익히면 됩니다.
한곳에 모인 사용량. 음악 생성은 출력 길이를 기준으로 과금되므로, 다른 모델 사용량과 함께 두면 여러 곳에 흩어진 청구서 대신 단일 대시보드에서 비용을 추적할 수 있습니다.

대가는 추상화 계층을 거친다는 점이며, 따라서 제공자 특유의 동작은 정규화됩니다. 최초 통합과 대부분의 프로덕션 사용 사례에서는 바로 이 정규화가 원하는 바입니다. 모델의 구체적인 동작을 이해해야 할 때는 웹사이트의 상세 페이지가 권위 있는 출처입니다.

첫 음악 요청 전 준비 사항

코드를 작성하기 전에 네 가지를 확인하세요. 그래야 첫 호출이 401이나 검증 오류가 아닌 오디오를 반환합니다.

1. API 키

HiAPI 계정에서 API 키를 발급받아야 합니다. 다른 어떤 키와도 마찬가지로 다루세요. 환경 변수에 보관하고, 절대 소스 코드에 커밋하지 말고, 로컬 개발과 프로덕션에 서로 다른 키를 사용해 하나를 폐기해도 다른 하나에 영향이 없도록 하세요.

export HIAPI_API_KEY="your_key_here"

2. 기본 URL과 엔드포인트 규약

모든 모델 호출은 동일한 기본 URL을 사용하며, 모델은 경로가 아니라 요청 내부에서 식별됩니다. 프로젝트에서 기본 URL에 대한 상수를 두면, 환경이 다를 때 한 곳만 수정하면 됩니다.

3. 자연어로 작성한 프롬프트

elevenlabs/music-v2.5는 원하는 음악을 설명하는 텍스트 프롬프트를 받습니다. 악보나 MIDI 파일은 필요 없습니다. 장르, 편성, 분위기, 예상 길이를 한두 문장으로 설명하면 시작하기에 충분합니다. 이후 섹션에서 재사용 가능한 레시피를 제공합니다.

4. 출력에 대한 올바른 기대

음악 생성은 JSON 악보가 아니라 오디오를 반환합니다. 응답 페이로드를 어떻게 처리할지 미리 계획하세요. 개발 중에는 파일로 쓰고, 프로덕션에서는 스트리밍하거나 저장합니다. 조각이 대략 얼마나 길어야 하는지 미리 정하세요. 길이는 요청과 과금 모두에 영향을 줍니다.

첫 요청 전에 한 가지 더: 가정을 코드에 하드코딩하기보다 웹사이트의 가격 패널에서 elevenlabs/music-v2.5의 현재 속도 제한과 가격을 확인하세요. 가격과 제한은 변하며, 통합은 이를 스크립트의 상수가 아니라 설정으로 읽어야 합니다.

curl로 첫 호출 보내기

curl로 시작하세요. curl은 여러분과 HTTP 요청 사이의 모든 계층을 제거하기 때문입니다. curl 호출이 성공하면 애플리케이션에서의 어떤 실패든 API가 아니라 애플리케이션 자체의 문제입니다.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/music-v2.5",
    "messages": [
      {
        "role": "user",
        "content": "Instrumental lo-fi hip hop, warm vinyl texture, mellow electric piano, soft brushed drums, 80 BPM, relaxed late-night mood, about 30 seconds."
      }
    ]
  }'

각 부분의 역할은 다음과 같습니다:

-sS는 진행률 출력을 조용히 유지하면서 오류는 계속 표시합니다. 출력을 파일로 붙여넣을 때 유용합니다.
URL은 통합 엔드포인트입니다. 모델 이름이 경로가 아니라 요청 본문에 나타난다는 점에 주목하세요.
Authorization: Bearer $HIAPI_API_KEY는 환경에서 키를 읽으므로 셸 기록에 평문으로 남지 않습니다. Windows에서는 set 또는 PowerShell의 $env: 문법으로 변수를 설정하세요.
Content-Type: application/json은 필수입니다. 이 엔드포인트는 폼 인코딩을 받지 않습니다.
model은 정확한 식별자 elevenlabs/music-v2.5입니다. 여기서 오타가 나면 일반 실패가 아니라 모델을 찾을 수 없다는 오류가 발생하므로 디버깅에 도움이 됩니다.
messages는 프롬프트를 사용자 메시지 콘텐츠로 전달합니다. 프롬프트를 하나의 메시지에 넣으세요. 길고 구조화된 프롬프트가 여러 메시지로 분산된 것보다 더 나은 결과를 냅니다.

응답 본문에는 생성된 오디오와 요청에 대한 메타데이터가 포함됩니다. 개발 중에는 출력을 파일로 리디렉션하여 결과를 즉시 들어볼 수 있게 하세요:

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json -o response.json

페이로드를 request.json에 넣고 -d @request.json으로 읽는 것은 일찍부터 들여야 할 습관입니다. 요청을 비교하고 검토할 수 있게 하며, 한 번에 매개변수 하나만 바꿀 때 재생하기 쉽습니다.

Python에서 동일한 호출 반복하기

curl 호출이 오디오를 반환하면 Python으로 이식하세요. 목표는 단순히 동작하는 스크립트가 아니라 작업 큐, API 핸들러, 노트북에서 복사·붙여넣기 편차 없이 호출할 수 있는 함수입니다.

import json
import os
import urllib.request

BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
MODEL = "elevenlabs/music-v2.5"

def generate_music(prompt: str, timeout: int = 120) -> dict:
    """HiAPI를 통해 elevenlabs/music-v2.5에 음악 프롬프트를 전송합니다."""
    api_key = os.environ.get("HIAPI_API_KEY")
    if not api_key:
        raise RuntimeError("HIAPI_API_KEY is not set")

    payload = {
        "model": MODEL,
        "messages": [{"role": "user", "content": prompt}],
    }

    request = urllib.request.Request(
        BASE_URL,
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request, timeout=timeout) as response:
        return json.loads(response.read().decode("utf-8"))

if __name__ == "__main__":
    result = generate_music(
        "Cinematic orchestral swell, strings and low brass, hopeful build, "
        "no percussion, about 20 seconds."
    )
    print(json.dumps(result, indent=2)[:500])

함수가 커져도 유지할 가치가 있는 몇 가지 결정이 있습니다:

표준 라이브러리를 우선하세요. urllib은 튜토리얼에서 의존성 변동을 피하게 해줍니다. 프로젝트가 이미 requests나 httpx를 사용한다면 변환은 기계적입니다. json=payload, headers=headers, timeout을 전달하면 됩니다.
타임아웃은 필수입니다. 음악 생성은 채팅 완성보다 오래 걸립니다. 기본값에 기대지 말고 명시적 타임아웃을 설정하세요. 요청하는 가장 긴 조각의 예상 생성 시간보다 긴 값을 선택하세요.
호출 시점에 키를 읽으세요. 가져올 때가 아니라 호출할 때 읽어야 같은 모듈이 로컬에서도, 런타임에 환경이 주입되는 컨테이너에서도 동작합니다.
구조화된 데이터를 반환하세요. 문자열을 출력하지 마세요. 오디오를 디스크에 쓸지, 객체 스토리지에 업로드할지, 클라이언트로 전달할지는 호출자가 결정합니다.

무언가를 구축하기 전에 Python 함수와 curl 호출이 같은 프롬프트에 대해 동등한 결과를 내는지 확인하세요. 이 일관성이 회귀 기준선입니다.

스타일, 분위기, 길이를 위한 프롬프트 레시피

음악 프롬프트는 세 가지 질문에 순서대로 답할 때 가장 잘 작동합니다. 어떤 장르와 편성인가, 어떤 감정적 톤인가, 얼마나 긴가. 모호한 프롬프트는 일반적인 출력을 낳고, 지나치게 긴 프롬프트는 중요한 설명어를 희석시킵니다. 목표는 밀도 있는 한 문장, 또는 짧은 세 구절입니다.

이것들을 복사·붙여넣기 가능한 출발점으로 삼고, 한 번에 한 차원씩만 조정하세요.

스타일 중심 레시피

Solo piano, felt hammers, close-miked, slow arpeggios in the style of a modern film score.
Upbeat synthwave, analog bass, gated reverb drums, arpeggiated lead, 120 BPM.
Acoustic folk ensemble, fingerpicked guitar, upright bass, light tambourine, organic room sound.
Ambient drone, layered pads, no rhythm section, slowly evolving texture.

분위기 중심 레시피

Warm and nostalgic, like a summer evening, major key, gentle dynamics.
Tense and minimal, low pulsing bass, sparse percussion, unresolved harmony.
Playful and bright, staccato strings, bouncy rhythm, light-hearted.
Melancholic and spacious, reverb-heavy, sparse piano, slow tempo.

길이 중심 레시피

길이는 프롬프트에 명확한 목표로 적어야 하며, 편곡과 일치해야 합니다. 느린 도입부와 긴 꼬리로 구성된 15초 요청은 어색하게 잘릴 것입니다.

... about 15 seconds, short intro, no outro, ends cleanly.
... about 30 seconds, one clear section, loopable ending.
... about 60 seconds, intro, main section, and a natural fade.

조합 예시

Lo-fi hip hop for focus, dusty vinyl crackle, soft electric piano, brushed drums, 80 BPM, calm and unhurried, about 30 seconds, loopable.

출력이 기대와 다를 때

시도할 때마다 변수 하나만 조정하세요. 그래야 무엇이 결과를 바꿨는지 알 수 있습니다.

너무 일반적임: 감정 단어를 구체적인 편성과 속도로 교체하세요. "Energetic"보다 "driving 16th-note bass at 128 BPM"이 더 강력합니다.
너무 복잡하거나 어수선함: 긍정 설명어를 더 추가하는 대신 악기를 명시적으로 제거하세요(no drums, no vocals, sparse arrangement).
길이가 어색함: 조각이 갑자기 끊기면 더 짧은 목표와 명확한 엔딩을 요청하고, 급하게 느껴지면 요청하는 섹션 수를 줄이세요.
스타일 표류: 장르와 편성을 프롬프트 앞쪽으로 옮기세요. 앞쪽 토큰의 가중치가 더 높습니다.

저장소에 작은 프롬프트 파일을 두고 효과가 있었던 레시피를 기록하세요. 이 파일은 어떤 단일 생성 조각보다도 가치가 큽니다. 프롬프트 작성이 반복 가능한 엔지니어링 산출물이 되기 때문입니다.

흔한 실수와 해결 방법

대부분의 첫 통합은 예측 가능한 몇 가지 방식으로 실패합니다. 추측을 시작하기 전에 이 체크리스트를 훑어보세요.

인증 실패

401은 거의 항상 요청 헤더 형식이 잘못되었거나 프로세스 환경에 키가 없음을 의미합니다. Bearer 뒤에 불필요한 공백이 있는지, 잘못된 .env 파일에서 키를 불러왔는지, export가 스크립트를 실행한 것과 다른 세션에서 수행되었는지 확인하세요. 키 자체가 아니라 키 길이를 출력해 값이 채워졌는지 확인하세요.

모델 식별자 불일치

모델을 찾을 수 없음 또는 검증 오류는 보통 model 문자열이 정확히 일치하지 않음을 의미합니다. elevenlabs/music-v2.5는 대소문자를 구분하며 슬래시를 포함합니다. 채팅 창에서 복사했다면 스마트 따옴표나 줄바꿈 잔여물이 있는지 확인하세요.

요청 본문 형식 오류

curl은 되는데 Python은 안 된다면 차이는 거의 항상 직렬화 문제입니다. JSON 문자열이 필요한 곳에 Python dict를 직접 전달하거나, json.dumps로 이중 인코딩하거나, Content-Type: application/json을 빠뜨리면 실제 원인과 무관해 보이는 서버 파싱 오류가 발생합니다. 코드가 보내는 정확한 요청 본문을 기록하고 동작하는 curl 페이로드와 문자 단위로 비교하세요.

긴 조각의 타임아웃

더 긴 길이는 더 긴 생성 시간을 요구합니다. 채팅 요청에 적합한 클라이언트 타임아웃은 긴 음악 요청을 잘라냅니다. 이 엔드포인트 전용으로 타임아웃을 높이고, 연결 수준 실패에만 백오프를 둔 재시도를 추가하세요. 이미 과금되었을 수 있는 요청을 맹목적으로 재시도하지 마세요.

프롬프트 길이와 내용

매우 긴 프롬프트나 API 자체에 대한 지시를 담은 프롬프트는 종종 더 나쁜 음악을 만듭니다. 프롬프트는 음악에 대해서만 이야기하게 하세요. 어제 효과가 있었던 프롬프트가 동작을 멈춘다면 스타일/분위기/길이 뼈대로 단순화한 뒤 다시 구성하세요.

응답을 텍스트로 처리하기

이 엔드포인트는 읽을 수 있는 전사 텍스트가 아니라 오디오 데이터를 반환합니다. 원시 응답 본문을 .txt 파일로 저장한 뒤 왜 재생이 안 되는지 의아해하는 것은 흔한 첫날 실수입니다. 올바른 오디오 확장자로 저장하고, 더 구축하기 전에 플레이어에서 파일이 열리는지 확인하세요.

오류가 정말 불명확하면 가능한 한 가장 작은 curl 요청으로 재현하세요. 그러면 문제가 API 계약에 있는지 여러분의 코드에 있는지 분리할 수 있습니다.

테스트 호출에서 반복 가능한 워크플로로

성공한 테스트 호출은 통합이 아니라 출발점입니다. 이 체크리스트로 팀이 의존할 수 있는 것으로 바꾸세요.

설정 외부화. 기본 URL, 모델 식별자, 타임아웃, 기본 길이 목표는 흩어진 문자열 리터럴이 아니라 설정에 두세요. 환경별 값은 환경에서 가져옵니다.
클라이언트 중앙화. 하나의 함수나 가벼운 클라이언트 클래스가 요청을 담당하게 하세요. 어떤 모듈도 음악 엔드포인트로의 HTTP 호출을 스스로 구성해서는 안 됩니다. 그렇지 않으면 헤더와 오류 처리에서 갈라집니다.
오류를 범주별로 처리. 인증, 검증, 타임아웃, 서버 오류를 구분하세요. 일시적 오류만 백오프와 상한을 두고 재시도하세요. 이미 출력을 생성하고 과금되었을 수 있는 요청은 절대 재시도하지 마세요.
오디오를 올바르게 저장. 결정적 키로 객체 스토리지에 쓰고, 프롬프트를 생성된 에셋과 함께 두고, 모델 식별자를 기록하세요. 나중에 결과를 재현하려면 당시에 무엇을 요청했는지 정확히 알아야 합니다.
길이를 일급 매개변수로 추적. 과금이 출력 길이를 따르므로 프롬프트 템플릿에 목표 길이를 명시하고 요청별로 기록해 비용 보고서가 사용량과 맞도록 하세요.
프롬프트 라이브러리 구축. 검증된 레시피를 버전 관리에 넣고 각 레시피의 용도를 짧게 적어 두세요. 새 팀원이 추측이 아니라 동작하는 프롬프트로 시작하게 됩니다.
동기와 비동기 경로 분리. 생성은 느릴 수 있습니다. 사용자 대면 기능이라면 작업을 제출하고 요청을 영속화한 뒤 워커가 모델을 호출하게 하세요. HTTP 핸들러가 생성 내내 열린 채로 있어서는 안 됩니다.
스모크 테스트로 검증. 고정된 짧은 프롬프트를 보내고 오디오 응답 형식이 올바른지 확인하는 테스트는 자격 증명과 계약 표류를 일찍 발견합니다.

매개변수와 제한을 더 깊이 이해할 준비가 되면, HiAPI의 elevenlabs/music-v2.5 모델 페이지가 가정을 하드코딩하기 전에 현재 기능을 확인할 수 있는 곳입니다.

모든 아티클 보기 →