video-to-sfx

Sonilo Video-to-SFX

Sonilo に動画を渡すと、映像に合った効果音を生成します。足音、衝撃音、環境音、UI サウンドなど、シーンに必要な音を生成できます。または、segments を使って特定の音を特定のタイミングに指定できます。生成はバックエンドで非同期タスクとして実行され、ツールが内部でポーリングして、保存済みファイルを返します。

セットアップ： setup-api-key スキルを参照してください。

⚠️ 料金： 以下の各ツールは、料金が発生する可能性のある API 呼び出しを行います。明示的に依頼された場合にのみ呼び出してください。

トランスポート：MCP または CLI

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

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

クイックスタート

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

video_to_sfx(
    video_path="~/Desktop/action-scene.mp4",
    prompt="Footsteps on gravel, distant traffic, a door slam"
)

Python（pip install sonilo）

from sonilo import Sonilo

client = Sonilo()  # reads SONILO_API_KEY

foley = client.video_to_sfx.generate(video="action-scene.mp4", prompt="Footsteps on gravel, distant traffic, a door slam")
foley.save("foley.wav")

# video_to_video_sfx: get the video back with the effects muxed in
video = client.video_to_video_sfx.generate(video="action-scene.mp4", segments=[{"start": 0, "end": 2, "prompt": "footsteps on gravel"}])
video.save("with_sfx.mp4")

JavaScript / TypeScript（npm install sonilo）

import { SoniloClient } from "sonilo";

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

const foley = await client.videoToSfx.generate({
  video: "./action-scene.mp4",
  prompt: "Footsteps on gravel, distant traffic, a door slam",
});

// video_to_video_sfx: get the video back with the effects muxed in
const video = await client.videoToVideoSfx.generate({
  video: "./action-scene.mp4",
  segments: [{ start: 0, end: 2, prompt: "footsteps on gravel" }],
});

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

sonilo video-to-sfx --video action-scene.mp4 --output foley.wav

内部では常に非同期で実行されます。CLI が送信とポーリングを行います。--format には wav|mp3|aac|flac を指定できます。

# the muxed video, from the CLI
sonilo video-to-video-sfx --video clip.mp4 --prompt "footsteps, distant thunder" --output foley.mp4

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

curl -X POST "https://api.sonilo.com/v1/video-to-sfx" \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  -F "[email protected]" \
  -F "prompt=Footsteps on gravel, distant traffic, a door slam"
# -> {"task_id": "..."}  poll GET /v1/tasks/{task_id} until status is succeeded/failed

すべての呼び出しはタスクベースです。エンドポイントは {"task_id": ...}（HTTP 202）を返し、status が終端状態になったら GET /v1/tasks/{task_id} から結果を取得します。MCP ツールはこのポーリングを代わりに行い、保存先のパスを直接返します。呼び出しがタイムアウトした場合にのみ task_id が表示されます（task-recovery を参照）。

ツール

ツール	説明
video_to_sfx(video_path? | video_url?, prompt?, segments?, audio_format?, output_directory?)	動画に合った効果音を生成します。音声のみを返します（元の動画は返しません）。
video_to_video_sfx(video_path? | video_url?, prompt?, segments?, output_directory?)	同様ですが、効果音を多重化した新しい .mp4 を返します。

パラメーター

パラメーター	型	デフォルト	備考
prompt	string	—	全体の説明（任意、最大 2000 文字）です。Sonilo に動画を独自に解釈させる場合は省略してください。
video_path	string	—	.mp4/.mov/.webm/.m4v/.gif（gif はアニメーションである必要があります）。音楽ツールより対応形式が限られています。最大 480s（8 分）。アカウントのアップロードサイズ上限が適用されます。
video_url	string	—	動画の HTTPS/HTTP URL です。video_path と video_url のどちらか一方のみ指定してください。
segments	list[dict]	—	特定の時間範囲に効果音を指定します：[{"start": float, "end": float, "prompt": str}, ...]。以下のルールを参照してください。最大 30 セグメントです。
audio_format	string	aac（.m4a）	wav、mp3、aac、または flac。video_to_sfx のみで使用します（video-to-video は常に .mp4 を出力します）。
output_directory	string	SONILO_MCP_BASE_PATH	絶対パス、またはベースパスからの相対パスです。

segments のルール

料金が発生する前にバックエンドで検証されます。無効なリストは 422/400 で拒否され、請求は発生しません。

• 最初のセグメントの start は 0 である必要があります。
• セグメントは連続している必要があります。各セグメントの end は、次のセグメントの start と一致する必要があります。
• 各 end は、その start より大きい必要があります。
• 各 prompt は空であってはならず、最大 200 文字です。
• 最後の end は、動画の実際の長さを超えてはなりません。
• セグメントの合計は最大 30 個です。

プロンプト

プロンプトは不要です。モデルが映像を読み取ります。品質を左右するのは、時間ごとに区切ったアクションマップです。画面に何が映っているか、それが何でできているか、何をするのかを秒単位で記述します。映像が真実の基準です。

有料の呼び出しの前に、正確な長さと既存の音声を確認し、480 s の上限を守ってください（超過すると422エラーで拒否され、切り詰められることはありません）。また、承認を得てください。失敗した実行は自動で返金されますが、再試行は新たな請求となります。

• 実行前の確認全般（動画、上限、クレジット、検証の確認）：references/preflight.md
• アクションマップの作成（シーンの基調、サウンドの組み合わせ、素材の語彙、セグメントのルール）：references/sfx-prompting.md

ワークフローのヒント

• Sonilo に動画全体を読み取らせ、判断させるには、prompt/segments を未設定のままにします。特定の音を特定の瞬間に割り当てる必要がある場合（例：2.3sでパンチが当たる、5.0sでドアがバタンと閉まる）は、segments を使用します。
• SFXをミックスした動画を受け取りたい場合は、video_to_sfx ではなく video_to_video_sfx を使用します。
• プロンプト：具体的に記述し、要素を組み合わせます。「トタン屋根に降る激しい雨」は「雨」より効果的です。
• 音楽と混同しないでください。 バックグラウンドスコアやサウンドトラックには、代わりに video-to-music を使用します。音楽とSFXの両方をバランスよくまとめ、1回の請求で生成するには、video-to-sound を使用します。
• 映像がありませんか？ text-to-sfx は、説明だけから単一のクリップを生成します。
• どのような音にすべきか分かりませんか？ まず video-analysis を実行してください。1回の呼び出しで映像から読み取ったサウンドデザインの概要が返されます。ショット単位の sfx_segments に加え、そのまま使えるクリップ全体の sfx_prompt（mode="sfx" を渡さない場合は音楽の概要も含む）が得られるため、プロンプトを推測して何度も生成し直すより効果的です。これは何も生成しない有料の呼び出しなので、概要が本当に不明確な場合に使用してください。ユーザーがすでに希望を伝えている場合には使用しないでください。

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

ここにあるすべてのツールは、すでにバックエンドで非同期処理されています。それでも、生成に時間がかかると TIME_OUT_SECONDS を超える場合があります。その場合、エラーに task_id が含まれます。ジョブは引き続き実行され（料金もすでに発生しています）。後から get_sfx_task(task_id)（ホスト型サーバーでは get_generation_task(task_id)）を呼び出して結果を取得してください。task-recovery を参照してください。

出力ファイル

• video_to_sfx：指定した audio_format（.wav/.mp3/.flac、またはデフォルトの aac の場合は .m4a）で保存されます。ファイル名はプロンプト（スラッグ化したもの）から付けられるか、sfx-<first 8 chars of the task id> となります。
• video_to_video_sfx：SFXをミックスした単一の .mp4 です。

エラー処理

よくあるエラー：401 無効なキー、402 残高不足／トライアル終了、413 ファイルサイズ超過、422 無効なパラメーターまたは不正な segments、429 レート制限。アカウント スキルを参照してください。