튜토리얼

음악 빠른 시작

Music API로 음악을 생성하는 방법을 알아보세요.

이 가이드에서는 Music API로 음악을 생성하는 방법을 알아봅니다.

ElevenLabs 음악 스킬을 사용해 AI 코딩 어시스턴트에서 음악 트랙을 생성하세요.

npx skills add elevenlabs/skills --skill music
Music API는 유료 사용자만 이용할 수 있습니다.

Music API 사용하기

1

API 키 생성

대시보드에서 API 키를 생성하세요. 이 키로 API에 안전하게 액세스할 수 있습니다.

키는 관리형 시크릿으로 저장하고, .env 파일을 통한 환경 변수 또는 앱 구성에서 직접 SDK에 전달하세요.

.env
ELEVENLABS_API_KEY=<your_api_key_here>
2

SDK 설치

환경 변수에서 API 키를 불러오기 위해 dotenv 라이브러리도 사용합니다.

pip install elevenlabs
pip install python-dotenv
3

API 요청 보내기

선택한 언어에 따라 example.py 또는 example.mts라는 새 파일을 만들고 다음 코드를 추가하세요.

# example.py
from elevenlabs.client import ElevenLabs
from elevenlabs.play import play
import os
from dotenv import load_dotenv
load_dotenv()
elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
track = elevenlabs.music.compose(
    prompt="Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
    music_length_ms=10000,
    model_id="music_v2_5",
)
# Save the track to a file
with open("path/to/music.mp3", "wb") as f:
    for chunk in track:
        f.write(chunk)

그런 다음 실행하세요.

python example.py

생성된 음악이 재생되는 것을 들을 수 있습니다.

작곡 플랜

작곡 플랜은 생성하려는 음악을 더 세밀하게 설명하는 JSON 객체입니다. 빠른 프로토타이핑에는 텍스트 프롬프트를 사용하고, 특정 청크 구조, 정확한 가사 타이밍 또는 복잡한 편곡이 필요할 때는 작곡 플랜을 사용하세요.

작곡 플랜 가이드

정밀한 제어를 위해 청크, 스타일, 가사로 곡을 구성하는 방법을 알아보세요.

작곡 플랜 생성하기

API를 사용해 프롬프트에서 작곡 플랜을 생성할 수 있습니다.

from elevenlabs.client import ElevenLabs
from elevenlabs.play import play
import os
from dotenv import load_dotenv
load_dotenv()
elevenlabs = ElevenLabs(
api_key=os.getenv("ELEVENLABS_API_KEY"),
)
composition_plan = elevenlabs.music.composition_plan.create(
    prompt="Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
    music_length_ms=10000,
    model_id="music_v2_5",
)
print(composition_plan)

위 코드는 다음과 유사한 작곡 플랜을 생성합니다.

{
  "chunks": [
    {
      "text": "[Intro]",
      "durationMs": 3000,
      "positiveStyles": [
        "electronic",
        "fast-paced",
        "rising synth arpeggio",
        "glitch fx",
        "filtered noise sweep",
        "soft punchy kick building tension",
        "high adrenaline"
      ],
      "negativeStyles": ["soft pads", "melodic vocals", "ambient textures"],
      "contextAdherence": "high"
    },
    {
      "text": "[Peak Drop]",
      "durationMs": 4000,
      "positiveStyles": [
        "full punchy drums",
        "distorted bass stab",
        "aggressive rhythmic hits",
        "rapid arpeggio sequences"
      ],
      "negativeStyles": ["smooth transitions", "clean bass", "slow buildup"],
      "contextAdherence": "high"
    },
    {
      "text": "[Final Burst]",
      "durationMs": 3000,
      "positiveStyles": [
        "glitch stutter",
        "energy burst vox chopped sample",
        "quick transitions",
        "snare rolls"
      ],
      "negativeStyles": ["long reverb tails", "fadeout", "gentle melodies"],
      "contextAdherence": "high"
    }
  ]
}

작곡 플랜 사용하기

작곡 플랜을 compose 메서드에 전달하여 음악을 생성할 수 있습니다.

# You can pass in composition_plan or prompt, but not both.
composition = elevenlabs.music.compose(
    composition_plan=composition_plan,
    model_id="music_v2_5",
)
play(composition)

세부 정보와 함께 음악 생성하기

음악을 생성할 때마다 프롬프트에서 작곡 플랜이 생성됩니다. 상세 응답 엔드포인트를 사용하면 이 플랜을 조회할 수 있습니다.

track_details = elevenlabs.music.compose_detailed(
    prompt="Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
    music_length_ms=10000,
    model_id="music_v2_5",
)
print(track_details.json) # json contains composition_plan and song_metadata. The composition plan will include lyrics (if applicable)
print(track_details.filename)
# track_details.audio contains the audio bytes

저작권 보호 자료

저작권 보호 자료가 포함된 음악이나 작곡 플랜을 생성하려고 하면 오류가 발생합니다. 여기에는 밴드나 음악가의 이름을 언급하거나 저작권 보호 가사를 사용하는 경우가 포함됩니다.

저작권 보호 자료가 포함된 프롬프트

이 경우 API는 대신 사용할 수 있는 프롬프트 제안을 포함한 bad_prompt 오류를 반환합니다.

try:
    # This will result in a bad_prompt error
    track = elevenlabs.music.compose(
        prompt="A song that sounds like 'Bohemian Rhapsody'",
        music_length_ms=10000,
        model_id="music_v2_5",
    )
  except Exception as e:
      if e.body['detail']['status'] == 'bad_prompt':
          prompt_suggestion = e.body['detail']['data']['prompt_suggestion']
          print(prompt_suggestion) # Prints: An epic rock ballad with dramatic tempo changes, operatic harmonies, and a narrative structure that blends melancholy with bursts of theatrical intensity.
          # Use the prompt suggestion to generate the track instead

저작권 보호 자료가 포함된 작곡 플랜

작곡 플랜을 생성할 때 저작권 보호 자료를 사용하는 스타일이 포함되면 bad_composition_plan 오류가 반환됩니다. 음악 프롬프트와 마찬가지로 오류 내에 제안된 작곡 플랜 composition_plan_suggestion이 반환됩니다.

유해한 자료가 포함된 작곡 플랜이나 프롬프트의 경우 제안 프롬프트는 반환되지 않습니다.

다음 단계

음악 스트리밍

전체 파일을 기다리지 않고 생성된 음악을 실시간으로 스트리밍하세요.

음악 인페인팅

기존 음악 트랙의 특정 섹션을 수정하거나 확장하세요.

API 레퍼런스

모든 Music API 파라미터와 응답 형식 살펴보기