Tutoriais

Guia rápido de música

Aprenda a gerar música com a API de Música.

Este guia mostra como gerar músicas com nossa API de Música.

Use a skill de música da ElevenLabs para gerar faixas de música com seu assistente de programação com IA:

npx skills add elevenlabs/skills --skill music
A API de Música está disponível apenas para usuários pagos.

Como usar a API de Música

1

Crie uma chave de API

Crie uma chave de API no painel aqui, que você usará para acessar a API com segurança.

Armazene a chave como um segredo gerenciado e passe-a aos SDKs como uma variável de ambiente por meio de um arquivo .env ou diretamente na configuração do seu app, conforme sua preferência.

.env
ELEVENLABS_API_KEY=<your_api_key_here>
2

Instale o SDK

Também usaremos a biblioteca dotenv para carregar nossa chave de API de uma variável de ambiente.

pip install elevenlabs
pip install python-dotenv
3

Faça a solicitação à API

Crie um arquivo chamado example.py ou example.mts, dependendo da linguagem escolhida, e adicione o código a seguir:

# 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)

Depois, execute-o:

python example.py

Você deverá ouvir a música gerada sendo reproduzida.

Planos de composição

Um plano de composição é um objeto JSON que descreve com mais detalhes a música que você quer gerar. Use prompts de texto para prototipagem rápida e planos de composição quando precisar de uma estrutura específica de trechos, sincronização precisa das letras ou arranjos complexos.

Guia de planos de composição

Saiba como estruturar músicas com trechos, estilos e letras para ter controle preciso.

Como gerar um plano de composição

Um plano de composição pode ser gerado a partir de um prompt usando a 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)

O código acima gerará um plano de composição semelhante ao seguinte:

{
  "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"
    }
  ]
}

Como usar um plano de composição

Um plano de composição pode ser usado para gerar música ao passá-lo para o método 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)

Como gerar música com detalhes

Para cada geração de música, um plano de composição é criado a partir do prompt. Você pode optar por recuperar esse plano usando o endpoint de resposta detalhada.

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

Material protegido por direitos autorais

Tentar gerar música ou um plano de composição que contenha material protegido por direitos autorais resultará em um erro. Isso inclui mencionar uma banda ou músico pelo nome ou usar letras protegidas por direitos autorais.

Prompts com material protegido por direitos autorais

Nesses casos, a API retornará um erro bad_prompt com uma sugestão de prompt que você poderá usar em vez disso.

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

Planos de composição com material protegido por direitos autorais

Se estilos que usam material protegido por direitos autorais forem usados ao gerar um plano de composição, será retornado um erro bad_composition_plan. Assim como nos prompts de música, um plano de composição sugerido, composition_plan_suggestion, será retornado no erro.

No caso de um plano de composição ou prompt que contenha material nocivo, nenhuma sugestão de prompt será retornada.

Próximas etapas

Transmita músicas

Transmita músicas geradas em tempo real em vez de esperar pelo arquivo completo

Inpainting de música

Modifique ou estenda seções específicas de uma faixa de música existente

Referência da API

Explore todos os parâmetros e formatos de resposta da API de Música