music

ElevenLabs 音楽生成

テキストプロンプトから音楽を生成します。インストゥルメンタルトラック、歌詞付きの楽曲に対応し、作曲プランを使って細かく制御できます。

コードを書く前のセットアップ： このプロジェクトで ELEVENLABS_API_KEY が設定されていない場合は、まずアプリのフォルダーから npx -y @elevenlabs/cli@latest onboard init を実行し、表示される手順に従ってください。ユーザーのサインインとプロジェクト用キーの保存が行われるため、キーを手動でコピーする必要はありません。それ以外の場合は、インストールガイドを参照してください。JavaScript では、@elevenlabs/* パッケージのみを使用してください。

以下の例はすべて、最も高度な生成モデルである music_v2_5 を使用しています。旧モデルが明示的に指定された場合にのみ、music_v2 または music_v1 を渡してください。

クイックスタート

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

audio = client.music.compose(
    prompt="A chill lo-fi hip hop beat with jazzy piano chords",
    music_length_ms=30000,
    model_id="music_v2_5",
)

with open("output.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

TypeScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createWriteStream } from "fs";

const client = new ElevenLabsClient();
const audio = await client.music.compose({
  prompt: "A chill lo-fi hip hop beat with jazzy piano chords",
  musicLengthMs: 30000,
  modelId: "music_v2_5",
});
audio.pipe(createWriteStream("output.mp3"));

CLI

elevenlabs music compose \
  --prompt "A chill lo-fi beat" \
  --music-length-ms 30000 \
  --model-id music_v2_5 \
  --output output.mp3

メソッド

メソッド	説明
music.compose	プロンプトまたは作曲プランから音声を生成します
music.stream	生成と同時に音声チャンクをストリーミングします（有料プラン）
music.composition_plan.create	細かく制御するための構造化プランを生成します
music.compose_detailed	音声、作曲プラン、メタデータを生成します。インペインティングを有効にするには、store_for_inpainting=True を渡します
music.compose_detailed_stream	音声と作曲プラン、メタデータ、任意の単語タイムスタンプを、Server-Sent Events としてストリーミングします
music.video_to_music	アップロードした 1 つ以上の動画ファイルから BGM を生成します
music.upload	後のインペインティングワークフローで使う音声ファイルをアップロードします。作曲プランまたは単語単位のタイムスタンプを任意で抽出できます
music.finetunes.list	アクセス可能な音楽ファインチューンを一覧表示します
music.finetunes.create	アップロードした音声から音楽ファインチューンをトレーニングします
music.finetunes.get	ファインチューンのステータスとメタデータを取得します
music.finetunes.update	ファインチューンのメタデータまたは公開範囲を更新します
music.finetunes.delete	音楽ファインチューンを削除します

パラメーターの詳細は、API リファレンスを参照してください。

music.upload は、インペインティング機能を利用できるエンタープライズクライアントが使用できます。

音楽ファインチューン

トレーニング用音声からファインチューンを作成するには、 POST /v1/music/finetunes を使用し、ステータスが completed になるまで get エンドポイントをポーリングします。取得した id を finetune_id として渡すと、音楽を作曲できます。

アクセス可能なファインチューンを管理するには、 list、 update、および delete エンドポイントを使用します。

動画から音楽を生成

アップロードした動画クリップから BGM を生成するには、 POST /v1/music/video-to-music （client.music.video_to_music）を使用します。これは、プロンプトベースの music.compose（POST /v1/music）とは別の機能です。

API は動画を順番に結合し、任意の自然言語による説明を受け付けます。また、upbeat や cinematic など最大 10 個のタグを使ってスタイルを調整できます。このエンドポイントのデフォルトは引き続き music_v1 です。最も高度なモデルを使用するには、model_id="music_v2_5" を渡してください。

3 つの任意フラグで生成結果を調整できます。use_audio_as_reference は動画自体の音声からジャンル、BPM、楽器編成、雰囲気を取り込みます。add_sfx は動画に合った効果音を追加します。separate_tracks は、ミキシング用に音楽と効果音を別ファイルにした ZIP を返します。

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

audio = client.music.video_to_music(
    videos=["trailer.mp4"],
    description="Build suspense, then resolve with a warm cinematic finish.",
    tags=["cinematic", "suspenseful", "uplifting"],
    model_id="music_v2_5",
)

with open("video-score.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

TypeScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createReadStream, createWriteStream } from "fs";

const client = new ElevenLabsClient();

const audio = await client.music.videoToMusic({
  videos: [createReadStream("trailer.mp4")],
  description: "Build suspense, then resolve with a warm cinematic finish.",
  tags: ["cinematic", "suspenseful", "uplifting"],
  modelId: "music_v2_5",
});

audio.pipe(createWriteStream("video-score.mp3"));

CLI

elevenlabs music video_to_music \
  --videos trailer.mp4 \
  --description "Build suspense, then resolve with a warm cinematic finish." \
  --tags cinematic \
  --model-id music_v2_5 \
  --output video-score.mp3

CLI では現在、リクエストごとに --videos ファイルを 1 つ、--tags の値を 1 つだけ受け付けます。複数の動画やタグを送信するには、Python または TypeScript SDK を使用してください。

現在の API スキーマによる制約：

• リクエストごとに動画ファイルを 1～10 個アップロードできます
• アップロードサイズの合計は 200 MB 以下にしてください
• 動画の合計時間は 600 秒以下にしてください
• 大まかな音楽の方向性には description を、簡潔なスタイルの手がかりには tags を使用してください

Composition Plans

music_v2_5 のコンポジションプランは、chunks の順序付きリストです。各チャンクには、それぞれの text（セクションラベル、歌詞、インラインの指示）、duration_ms、positive_styles、negative_styles、および context_adherence（low、medium、high。デフォルトは high）を指定します。1 つのプランにつき最大 30 チャンク、各チャンクは 3,000～120,000 ms、全体の長さは 3 秒～10 分です。各チャンクの text は最大 6,132 文字、1 行あたり最大 200 文字で、最大 30 行まで指定できます。

まずプランを生成して編集し、その後に作曲します。

plan = client.music.composition_plan.create(
    prompt="An epic orchestral piece building to a climax",
    music_length_ms=60000,
    model_id="music_v2_5",
)

# Edit chunks in place
plan["chunks"][0]["text"] = "[Intro]\nQuiet strings rising"

audio = client.music.compose(
    composition_plan=plan,
    model_id="music_v2_5",
)

const plan = await client.music.compositionPlan.create({
  prompt: "An epic orchestral piece building to a climax",
  musicLengthMs: 60000,
  modelId: "music_v2_5",
});

plan.chunks[0].text = "[Intro]\nQuiet strings rising";

const audio = await client.music.compose({
  compositionPlan: plan,
  modelId: "music_v2_5",
});

または、セクションごとの歌詞とスタイルを制御するため、プランを手動で作成します。

composition_plan = {
    "chunks": [
        {
            "text": "[Verse]\nWalking down an empty street",
            "duration_ms": 15000,
            "positive_styles": ["pop", "upbeat", "female vocals", "acoustic guitar"],
            "negative_styles": ["dark", "slow"],
            "context_adherence": "high",
        },
        {
            "text": "[Chorus]\nThis is my moment",
            "duration_ms": 15000,
            "positive_styles": ["powerful vocals", "full band"],
            "negative_styles": [],
            "context_adherence": "high",
        },
    ]
}

audio = client.music.compose(composition_plan=composition_plan, model_id="music_v2_5")

const compositionPlan = {
  chunks: [
    {
      text: "[Verse]\nWalking down an empty street",
      durationMs: 15000,
      positiveStyles: ["pop", "upbeat", "female vocals", "acoustic guitar"],
      negativeStyles: ["dark", "slow"],
      contextAdherence: "high",
    },
    {
      text: "[Chorus]\nThis is my moment",
      durationMs: 15000,
      positiveStyles: ["powerful vocals", "full band"],
      negativeStyles: [],
      contextAdherence: "high",
    },
  ],
};

const audio = await client.music.compose({
  compositionPlan,
  modelId: "music_v2_5",
});

ジャンル、楽器編成、ボーカルスタイルなど、より大まかな特徴は text ではなく positive_styles に指定してください。最初のチャンクのスタイルが全体の雰囲気を決めるため、そこには 6～7 個のスタイルを含めてください。

Output Formats

生成する音声形式を選択するには、compose、detailed compose、または stream リクエストで output_format クエリパラメーターを使用します。auto はモデルに適した MP3 形式を選択します。music_v2 と music_v2_5 では、mp3_48000_192 が選択されます。より高いビットレートの MP3 オプションには、mp3_48000_240 と mp3_48000_320 があります。

Streaming

有料プランでは、ファイル全体が完成するのを待たずに、生成された音声チャンクをストリーミングできます。

from io import BytesIO

stream = client.music.stream(
    prompt="A driving synthwave track with arpeggiated leads",
    music_length_ms=30000,
    model_id="music_v2_5",
)

buffer = BytesIO()
for chunk in stream:
    if chunk:
        buffer.write(chunk)

const stream = await client.music.stream({
  prompt: "A driving synthwave track with arpeggiated leads",
  musicLengthMs: 30000,
  modelId: "music_v2_5",
});

const chunks: Buffer[] = [];
for await (const chunk of stream) {
  chunks.push(chunk);
}

Detailed streaming

音声の受信中に生成された音楽のメタデータが必要なアプリケーションでは、詳細ストリーミングを使用します。POST /v1/music/detailed/stream は、detailed compose と同じプロンプトまたはコンポジションプランの本文を受け付け、text/event-stream をストリーミングし、with_timestamps を指定すると単語ごとのタイムスタンプを含めることができます。

elevenlabs music compose_detailed_stream \
  --prompt "A bright indie pop hook with warm guitars" \
  --music-length-ms 30000 \
  --model-id music_v2_5 \
  --with-timestamps true \
  --output-format auto

Inpainting

インペインティングでは、保存済みの曲を編集または延長するため、1 つのコンポジションプラン内で 音声参照チャンク（保存済みの曲を変更せずに切り出したスライス）と新しい 生成チャンク を組み合わせます。

ステップ 1 — 新しい生成結果を保存するか、既存の音声をアップロードして、song_id を取得します。

# Option A: keep a generation for later editing
result = client.music.compose_detailed(
    prompt="An upbeat pop song with verse and chorus",
    music_length_ms=60000,
    model_id="music_v2_5",
    store_for_inpainting=True,
)
song_id = result.song_id

# Option B: upload an existing track and extract its plan
uploaded = client.music.upload(
    file=open("my-song.mp3", "rb"),
    extract_composition_plan="music_v2_5",
)
song_id = uploaded.song_id
composition_plan = uploaded.composition_plan

import { createReadStream } from "fs";

// Option A: keep a generation for later editing
const result = await client.music.composeDetailed({
  prompt: "An upbeat pop song with verse and chorus",
  musicLengthMs: 60000,
  modelId: "music_v2_5",
  storeForInpainting: true,
});
let songId = result.songId;

// Option B: upload an existing track and extract its plan
const uploaded = await client.music.upload({
  file: createReadStream("my-song.mp3"),
  extractCompositionPlan: "music_v2_5",
});
songId = uploaded.songId;
const compositionPlan = uploaded.compositionPlan;

ステップ 2 — 保存済みの音声を参照し、変更したい部分を再生成するプランを作成します。

plan = {
    "chunks": [
        {"song_id": song_id, "range": {"start_ms": 0, "end_ms": 30000}},
        {
            "text": "[Chorus]\nWe're rising up tonight",
            "duration_ms": 30000,
            "positive_styles": ["bigger drums", "layered vocals", "anthemic"],
            "negative_styles": ["sparse"],
            "context_adherence": "high",
        },
    ]
}

audio = client.music.compose(composition_plan=plan, model_id="music_v2_5")

const plan = {
  chunks: [
    { songId, range: { startMs: 0, endMs: 30000 } },
    {
      text: "[Chorus]\nWe're rising up tonight",
      durationMs: 30000,
      positiveStyles: ["bigger drums", "layered vocals", "anthemic"],
      negativeStyles: ["sparse"],
      contextAdherence: "high",
    },
  ],
};

const audio = await client.music.compose({
  compositionPlan: plan,
  modelId: "music_v2_5",
});

保存済みのスライスをコピーせずにその雰囲気に合わせるには、conditioning_ref（最大 30,000 ms）と、low、medium、high、xhigh のいずれかの condition_strength を生成チャンクに設定します。最初のチャンクに設定したコンディショニングは、後続のすべてのチャンクに影響します。

インペインティングの全パラメーターについては、API Reference を参照してください。

Content Restrictions

• 特定のアーティスト、バンド、著作権で保護された歌詞には言及できません
• bad_prompt エラーには、別の表現を示す prompt_suggestion が含まれます
• bad_composition_plan エラーには、composition_plan_suggestion が含まれます

Error Handling

try:
    audio = client.music.compose(prompt="...", music_length_ms=30000)
except Exception as e:
    print(f"API error: {e}")

try {
  const audio = await client.music.compose({
    prompt: "...",
    musicLengthMs: 30000,
  });
} catch (err) {
  console.error("API error:", err);
}

よくあるエラー：401（無効なキー）、422（無効なパラメーター）、429（レート制限）。

References

• インストールガイド
• API リファレンス