video-to-music

Sonilo Video-to-Music

完成した動画を Sonilo に渡すと、編集に合わせたオリジナルの楽曲を作曲します。ペース、動き、感情を動画に合わせ、トランジションやビートドロップも編集に合わせたうえで、動画とまったく同じ長さに仕上げます。これが Sonilo の主力機能です。すべてのトラックはライセンス処理済み（音楽は Shutterstock のライセンスを使用）で、ソーシャルメディア、ブランドコンテンツ、広告に商用利用できます。

セットアップ： Sonilo MCP サーバーへの接続と認証については、setup-api-key スキルを参照してください。認証には sonilo login（キー不要）または SONILO_API_KEY を使用します。

⚠️ 費用： 以下の各ツールは、料金が発生する場合のある API 呼び出しを行います。ユーザーが実際に生成を依頼した場合にのみ呼び出してください。無料トライアルの実行回数が残っているか不明な場合は、get_account_services（account スキルを参照）を確認してください。

接続方式：MCP または CLI

セッション開始時にどちらか一方を選び、そのセッションでは使い続けてください。1 つのジョブ内で両方を混在させないでください。選択した方式をユーザーに伝える必要はありません。

1. このセッションで Sonilo MCP ツール（video_to_music など）が利用可能な場合 — それらを使用してください。シェルが不要で、非常に長い生成処理にも対応できる唯一の方法であるため、こちらを推奨します。入力内容ではなく認証に失敗した場合、このセッションではこの方式を利用できません。再試行するのではなく、2 に進んでください。
2. 利用可能な Sonilo MCP ツールはないが、sonilo account が終了コード 0 を返す場合 — 以下の CLI コマンドを使用してください。同じ API、同じアカウント、同じ認証情報ファイルを使用します。sonilo whoami ではなく、sonilo account で確認してください。whoami はサインアウト中でも終了コード 0 を返すため、サインイン済みかどうかを判別できません。
3. どちらも利用できない場合 — 処理を中止し、setup-api-key スキルを実行してください。回避策として curl で api.sonilo.com を呼び出さないでください。どちらの方式もアップロード、ポーリング、再試行に対応していますが、単独のリクエストでは対応できません。

クイックスタート

MCP ツール呼び出し（推奨）

video_to_music(
    video_path="~/Desktop/trailer.mp4",
    prompt="Build suspense, then resolve with a warm cinematic finish"
)

生成されたファイルを SONILO_MCP_BASE_PATH（デフォルトは ~/Desktop）に保存し、保存先のパスをテキストで返します。

Python（pip install sonilo）

from sonilo import Sonilo

client = Sonilo()  # reads SONILO_API_KEY

score = client.video_to_music.generate(video="trailer.mp4", prompt="Build suspense, then resolve with a warm cinematic finish")
score.save("score.m4a")

# video_to_video_music: get the video back with the music muxed in
video = client.video_to_video_music.generate(video="trailer.mp4", prompt="cinematic, uplifting")
video.save("scored.mp4")

video_to_music の preserve_speech=True を使用するには、非同期パスが必要です。generate() ではなく generate_async() を使用すると、追加の vocals／mux／ducked 出力を取得できます。全体の手順については、sonilo-python の README を参照してください。

JavaScript／TypeScript（npm install sonilo）

import { SoniloClient } from "sonilo";

const client = new SoniloClient(); // reads SONILO_API_KEY

const score = await client.videoToMusic.generate({
  video: "./trailer.mp4",
  prompt: "Build suspense, then resolve with a warm cinematic finish",
});

// video_to_video_music: get the video back with the music muxed in
const video = await client.videoToVideoMusic.generate({
  video: "./trailer.mp4",
  prompt: "cinematic, uplifting",
});

videoToMusic の preserveSpeech: true を使用するには、非同期パスが必要です。.generate() ではなく .submit() と client.tasks.wait() を使用してください。全体の手順については、sonilo-js の README を参照してください。

CLI（npm install -g sonilo-cli または pip install sonilo-cli）

sonilo video-to-music --video trailer.mp4 --prompt "Build suspense, then resolve with a warm cinematic finish" --output score.m4a

--format wav、--preserve-speech、--isolate-vocals を指定すると、それぞれ video-to-music は非同期の送信・ポーリング方式に切り替わります。

# the muxed video, from the CLI
sonilo video-to-video-music --video trailer.mp4 --prompt "cinematic, uplifting" --output scored.mp4

cURL（生の REST API、MCP ホストなし）

curl -X POST "https://api.sonilo.com/v1/video-to-music" \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  -F "[email protected]" \
  -F "prompt=Build suspense, then resolve with a warm cinematic finish" \
  --output score.m4a

video_to_music は、アップロードしたファイルの代わりに video_url フォームフィールドも受け付けます。どちらか一方のみを指定し、両方を指定しないでください。

ツール

ツール	説明
video_to_music(video_path? | video_url?, prompt?, preserve_speech?, output_format?, ducking?, variants_num?, prompt_influence?, stems?, output_directory?)	動画に楽曲を付けます。ペース／動き／感情を合わせ、動画とまったく同じ長さに仕上げます。音声のみを返します（動画自体は多重化されません）。
video_to_video_music(video_path? | video_url?, prompt?, segments?, keep_original_sound?, ducking?, preserve_speech?, variants_num?, prompt_influence?, output_directory?)	同様に楽曲を付けますが、音楽を多重化した新しい .mp4 を返します。デフォルトでは元動画の音声は削除されます。keep_original_sound を参照してください。

パラメーター

パラメーター	型	デフォルト	備考
prompt	string	—	任意のスタイルヒントです。映像に完全に委ねる場合は省略してください。
video_path	string	—	絶対パス、または SONILO_MCP_BASE_PATH からの相対パスです。.mp4/.mov/.avi/.wmv/.webm/.mkv に対応しています。最大 360s（6 min） で、アカウントのアップロードサイズ上限（通常は 300 MB）の対象です。
video_url	string	—	動画ファイルの HTTPS URL です。video_path と video_url のどちらか一方を指定してください。
preserve_speech	bool	false	元の音声を聞こえる状態に保ちます。video_to_music では、vocals 音声ステムと、すぐに使える mux（音声＋音楽をミックスしたもの）も返します。この場合、ストリーミングではなく非同期（送信＋ポーリング）で実行されるため、少し時間がかかりますが、ツールは完了まで待機します。
ducking	bool | null	video_to_music ではサーバーのデフォルトで ON、video_to_video_music では false	生成した音楽の音量を元の音声の下げます。無料で、ベストエフォートです。video_to_video_music では、keep_original_sound または preserve_speech と併用した場合にのみ機能します。どちらも指定しない場合、出力にダッキング対象となる元の音声は残りません。
keep_original_sound	bool	false	video_to_video_music 専用です。結果がおかしく聞こえる場合は、このパラメーターを使ってください。 デフォルトでは、返される .mp4 には生成された音楽のみが含まれ、元の音声の会話、室内音、効果音はなくなります。true にすると、元の音声全体を音楽とミックスして残せます。また、ducking=true を追加すると、音楽を均一にミックスするのではなく、音声の下に下げられます。keep_original_sound は preserve_speech より優先されます。
variants_num	int	1	1～10 です。1 回のリクエストで、異なるクリエイティブな方向性（同じものを再レンダリングしたものではなく、異なるテイク）を指定した数だけ生成します。費用は数に比例して増加し、1 を超える値は無料トライアルの対象外です。必ず事前にユーザーに数を確認してください。 1 を超えると、バリアントごとに 1 つのファイルが書き出され、バックエンドの非同期モードが強制されます。
prompt_influence	float | null	API のデフォルトは 0.5	0～1 です。映像自体の印象と比べて、音楽がプロンプトにどの程度忠実に従うかを指定します。値が低いほど映像の印象が優先され、高いほど指定内容が強く反映されます。無料で、モードやファイル数は変わりません。ユーザーから追従度を上げる、または下げるよう求められた場合を除き、省略してください。
stems	bool	false	video_to_music 専用です。video_to_video_music にはこのパラメーターはありません。無料です。 生成された各トラックを、drums、bass、vocals、other の 4 つの分離された楽器トラックに分割し、加工されていないフルミックスと併せて返します。動画本来の音声には一切手を加えません。REST では非同期モードでのみ使用できます（mode=async なしで stems=true を指定すると 400 になります）。ステムを参照してください。
output_format	string	m4a	video_to_music 専用です。video_to_video_music にはこのパラメーターはなく、常にミックス済みの .mp4 を出力します。m4a または wav を指定できます。wav（および preserve_speech／ducking）を指定すると、バックエンド内部で非同期モードが実行されます。
output_directory	string	SONILO_MCP_BASE_PATH	絶対パス、またはベースパスからの相対パスです。

ステム

video_to_music で stems=true を指定すると、生成された各トラックが 4 つの楽器トラック（drums、bass、vocals、other）に分離され、無料で追加取得できます。フルミックスはそのままで、タスク結果では audio の隣にある stems 配列としてステムが返されます。

"stems": [
  {
    "stream_index": 0,
    "drums":  { "url": "…", "content_type": "audio/mp4", "file_size": 2913044 },
    "bass":   { "url": "…", "content_type": "audio/mp4", "file_size": 2870211 },
    "vocals": { "url": "…", "content_type": "audio/mp4", "file_size": 2794560 },
    "other":  { "url": "…", "content_type": "audio/mp4", "file_size": 3011830 }
  }
]

利用時に重要な点は次のとおりです。

• 分離されるのは生成された音楽であり、動画自体の音声ではありません。 vocals ステムには、生成されたスコアに含まれる歌声が入ります。スコアの大半はインストゥルメンタルなので、通常はほぼ無音です。これは想定どおりの動作であり、バグではありません。元の音声の話し声を分離するには、代わりに preserve_speech（別の機能）を使用してください。
• REST では非同期のみです。 stems=true には mode=async が必要です（それ以外では 400 が返されます）。202 と task_id が返されるので、/v1/tasks/{task_id} をポーリングしてください。MCP ツールは常に非同期のため、ホステッドサーバーではこのパラメーターをそのまま使用できます。
• すべての提供形態で利用できます（2026-08-17 に確認済み）：REST、ホステッド MCP サーバー、ローカルの sonilo-mcp パッケージ（>= 0.18.0）、SDK（sonilo npm >= 0.16.0、PyPI >= 0.15.0）、CLI（--stems、npm sonilo-cli >= 0.15.0、PyPI sonilo-cli >= 0.14.0）。
• トラックとの対応付けには、配列の位置ではなく stream_index を使用してください。 分離に失敗したストリームは返されないため、stems の数は audio より少ない場合があります。
• stems_error は生成の失敗を意味しません。 分離が全部または一部失敗した場合、あるいはスキップされた場合、タスクには stems_error の文字列が含まれます。部分的な stems 配列と同時に返されることもあります。生成自体は成功しており、すべての audio URL は有効です。ステムが欠けている場合は、追加データが欠けているものとして扱い、再試行や返金の理由にしないでください。
• 所要時間： 分離は生成完了後に実行されます。通常はさらに 2〜6 分かかり、30 分後に打ち切られます（その場合は stems_error が返されます）。
• 4 つのステム名は固定です（htdemucs による分離）。ピアノ、シンセ、ギター、ストリングスなどのメロディ楽器は other に分類されます。
• 形式： ステムの形式は通常 output_format に従います。実際に返された形式は各ステムの content_type を確認してください。

プロンプト

プロンプトは必要ありません。モデルが動画を読み取ります。短く構成したブリーフを加えると、動画だけでは伝えられない意図、つまりジャンル、印象づけたい場面、避けたい音を伝えられます。

有料リクエストの前に、正確な長さと既存の音声を確認し、360 s の上限を守ってください（超過すると 422 エラーで拒否され、切り詰められることはありません）。また、事前に承認を得てください。失敗した実行は自動返金されますが、自分で再試行すると新たに課金されます。まずブリーフを作成してから一度だけ生成し、再生成を繰り返すのではなくプロンプトを調整してください。

• 実行前の確認事項（動画の確認、上限、クレジット、検証）：references/preflight.md
• スタイルプロンプトの作成（音声ブリーフ、ジャンル・エネルギーの表現、preserve_speech、セグメント化された音楽）：references/music-prompting.md

ワークフローのヒント

• プロンプト： スタイルのヒント（例：「映画のような、心を高揚させる」）で結果を調整できますが、プロンプトは任意です。Sonilo はすでに映像を読み取っています。
• トークヘッド動画やナレーション付き動画では preserve_speech を使用： 元の動画に、ユーザーが残したい会話やナレーションがある場合は、preserve_speech=true を設定してください。動作はツールによって異なります。video_to_music では、音楽、分離された音声ステム、すぐに使えるようにミックスされた結合ファイル（mux）が得られます。自分で再ミックスせず、mux をそのまま使用してください。video_to_video_music では、個別のステムや mux ファイルはありません。音声を結合した単一の出力動画で、元の音声が聞こえる状態に保たれます。
• 楽曲を組み込んだ動画を戻したい場合： video_to_music ではなく video_to_video_music を使用してください。入力は同じですが、出力は音声だけではなく新しい .mp4 です。**デフォルトでは元の音声が削除されることをユーザーに伝えてください。**動画に会話、ナレーション、または効果音があり、それらも聞こえるようにしたい場合は、keep_original_sound=true を渡してください（声を前面に保つには ducking=true を追加します）。分離した音声だけを残すには、preserve_speech=true を指定してください。「音楽は入っているけれど、ナレーションが消えた」という報告は、常にこれが原因です。
• 一度に複数のテイクを作成： variants_num=3 を指定すると、3 回の再生成ではなく、1 回のリクエストで異なる方向性の結果を 3 つ返します。料金は 3 倍で、無料トライアルの対象にはなりません。呼び出す前に料金を伝えてください。
• 楽曲の楽器を個別のファイルで取得したい場合（リミックス、バランス調整、または特定の楽器を外すため）：video_to_music で stems=true を指定してください。無料ですが、非同期のみの対応で、まだすべての環境で使えるわけではありません。また、分割されるのは生成された音楽で、元の音声ではありません。ステムを参照してください。
• 長さ： 常に元の動画に合わせて自動調整されるため、長さを尋ねる必要はありません。
• 効果音も必要ですか？ 同じ動画に対して音楽と効果音をバランスよく生成する場合、1 回の呼び出しで料金も 1 回分にするには、これと video-to-sfx を別々に呼び出すのではなく、video-to-sound を使用してください。
• どのような音にすればよいかわからない場合： まず video-analysis を実行してください。1 回の呼び出しで、セクションの構成案に加え、映像から読み取ったすぐに使える生成プロンプトが返されます（mode="music" を渡さない限り、サウンドデザインの概要も返されます）。プロンプトを推測して何度も生成し直すより効果的です。料金が発生しますが、生成は行われないため、要件が本当に不明確な場合に使用してください。ユーザーがすでに希望を伝えている場合には使用しないでください。
• コンテンツの制限： プロンプトで特定のアーティスト、バンド、または著作権で保護された歌詞に言及することはできません。

タイムアウトした呼び出しからの復旧

video_to_music（preserve_speech／ducking／stems／output_format="wav" のいずれも指定しない場合）は、1 回の呼び出しで結果をストリーミングします。バックエンドの非同期モードを有効にするすべてのバリエーションと、常に非同期の video_to_video_music は、TIME_OUT_SECONDS の設定が非常に長くてもタイムアウトすることがあります。その場合、エラーメッセージに task_id が含まれます。バックエンドでは生成処理が続行され、料金もすでに発生しています。結果の準備ができたら、get_sfx_task(task_id) を呼び出してください（ホステッドサーバーでは get_generation_task(task_id)）。task-recovery スキルを参照してください。

出力ファイル

• video_to_music：デフォルトでは .m4a（指定した場合は .wav）です。ファイル名はプロンプト（スラッグ化したもの）または sonilo-<timestamp>.m4a に基づきます。複数のストリームを並行して生成すると、末尾に -<index> が付きます。
• video_to_music(preserve_speech=true)：<base>-vocals.<ext>（分離された音声）と <base>-mux.<ext>（音声と音楽を結合したもの。実際に使用するファイル）も保存されます。
• video_to_video_music：楽曲が結合された単一の .mp4 です。

エラー処理

よくあるエラー：401 無効なキー、402 残高不足／トライアル終了、413 ファイルサイズ超過、422 無効なパラメーター（例：動画が 360 s の上限を超えている）、429 レート制限。account スキルで呼び出し前にトライアル／使用状況を確認してください。正確な復旧手順については、sonilo-mcp README のエラー表を参照してください。