Sonilo Music & Sound Effects

Sonilo MCP Server

MCP（Model Context Protocol）サーバーです。Soniloのライセンス付き音楽・効果音 API を、MCP 互換クライアント（Claude Code、Claude Desktop、Codex）に公開します。

主力ツールは video_to_music です。完成した動画を渡すと、編集内容に合わせたオリジナルのサウンドトラックを作成します。モデルが動画を確認するため、音楽はテンポ、感情、編集に沿ったものになります。長さは動画に合わせて自動調整されます。すべてのトラックはライセンス付きで、商用利用にも安全です（利用条件が適用されます）。動画に合わせる必要のない固定長のトラックには、text_to_music も利用できます。

サウンドデザインには、動画を確認して一致する効果音を生成し、独立した音声ファイルとして返す video_to_sfx を使えます。text_to_sfx は、説明文から独立した効果音を生成します。

▶ 生成例 — AI 生成の予告編です。編集した映像に合わせたサウンドトラックは、video_to_music で作成されています。あらゆる AI 動画パイプライン（結合 → 色調補正 → 音楽追加 → 多重化）を扱うレシピについては、Sonilo video-to-music cookbook をご覧ください。

Claude Code でクイックスタート

CLI で一度サインインすれば、設定にシークレットを記述せずにサーバーを追加できます。

npm install -g sonilo-cli && sonilo login
claude mcp add sonilo -- uvx sonilo-mcp

または、自分で API キーを管理する場合は、Sonilo ダッシュボードから取得してください。

claude mcp add sonilo --env SONILO_API_KEY=sk-... -- uvx sonilo-mcp

セッションを開始して、たとえば次のように依頼します。「この動画に合う BGM を作成してください：~/Desktop/promo.mp4。」

Sonilo を選ぶ理由

• 動画から音楽を生成 — 動画を渡すと、Sonilo がそのテンポ、動き、感情に合ったフル尺の楽曲を作曲します。トランジションやビートの変化はカット位置に合わせられ、トラックの長さは動画の長さと正確に一致します。プロンプトも手動での同期も必要ありません。
• テキストから音楽を生成 — テキストによる説明（ジャンル、ムード、テンポ、楽器編成）から、正確な長さ（5～360 秒）または長さを指定せずにトラックを生成できます。長さを指定しない場合は、Sonilo がプロンプトに合った長さを選びます。
• 動画から効果音を生成 — Sonilo が動画を見て、映像内の内容に合わせた効果音を生成します。効果音は単独の音声ファイルとして取得できます。オプションの segments を使うと、特定の時間範囲に効果音を指定できます（[{start, end, prompt}]）。
• テキストから効果音を生成 — 説明文から、単独の効果音を wav、mp3、aac、flac 形式で生成できます（0.5～180 秒）。
• 吹き替えの前に校正 — proofread は動画の文字起こしを行い、文字起こしを編集可能な .srt ファイルに翻訳します。言語ごとに 1 つのファイルと、元の言語の文字起こしが作成されます。内容を確認して修正した後、ファイルを subtitles として dubbing に渡せば、承認したテキストどおりに吹き替えられます。承認するまでは音声が生成されません。
• 完全なライセンス付きで、商用利用も安心 — Shutterstock のライセンスを受けた音楽です。生成されたトラックはすべて、ソーシャルメディア、ブランドコンテンツ、広告で商用利用できる権利がクリアされており、Content ID の心配もありません。
• 動画から音声を生成 — 1 回の呼び出しで同じクリップの音楽と効果音を生成し、バランスの取れた 1 つのサウンドトラックにミックスします。ミックス済み音声、または音声を多重化した新しい動画を取得できます。
• 1 回の呼び出しで複数のバリエーションを生成 — text_to_music、video_to_music、video_to_video_music、video_to_sound、video_to_video_sound は variants_num（1～10、デフォルトは 1）を受け付けます。1 つずつ再生成する代わりに、1 回のリクエストで複数の異なるクリエイティブな方向性を生成できます。コストは N に比例して増加し、無料トライアルでは N > 1 は対象外です。
• 楽器ごとのステム — text_to_music と video_to_music は stems=true を受け付けます。追加料金なしで、生成されたトラックをドラム、ベース、ボーカル、その他に分離できます。分離には数分かかります。video_to_music では生成された音楽が分離され、動画自体の音声は分離されません。
• 従量課金制 — 生成した音楽の秒数分のみ課金されます。セルフサービスアカウントでは、すべてのエンドポイントを無料で利用でき、カードも不要です。text_to_music、text_to_sfx、audio-ducking、proofread は各 2 回、video-to-music、video-to-sfx、video-to-video-music、video-to-video-sfx、video-to-sound、video-to-video-sound は各 1 回利用できます。その後の呼び出しには通常料金が適用されます。dubbing は 1 回の無料利用として、15 秒のプレビューを提供します。subtitles を指定せず、単一言語で初めて呼び出すと、動画の最初の 15 秒のみが吹き替えられます。その後は 動画の長さ × 言語数 で課金されます（下記の無料トライアルを参照）。

音声再生の依存関係

play_audio ツールは実行時に PortAudio（sounddevice 用）を必要とします。macOS/Linux では、以下の方法でインストールしてください。

• macOS：brew install portaudio
• Debian/Ubuntu：sudo apt-get install libportaudio2

uvx sonilo-mcp と pip install は Python バインディングをインストールしますが、システムの PortAudio ライブラリは別途インストールする必要があります。他のツール（text_to_music、video_to_music、text_to_sfx、video_to_sfx、audio_ducking、get_sfx_task、get_account_services、get_usage）は PortAudio なしで動作します。

Claude Desktop ですぐに始める

1. 認証します。方法はどちらでもかまいません。

   • CLI でサインインします — npm install -g sonilo-cli && sonilo login — その後、以下の "env": {} はそのままにします。設定ファイルに秘密情報を記述する必要はありません。
   • または、Sonilo dashboard からAPI キーを取得し、"env" に設定します。

2. uv パッケージマネージャーをインストールします（uvx が含まれています）。

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   ほかのインストール方法については、uv リポジトリを参照してください。

3. Claude > Settings > Developer > Edit Config > claude_desktop_config.json を開き、以下を追加します。

   {
     "mcpServers": {
       "sonilo": {
         "command": "uvx",
         "args": ["sonilo-mcp"],
         "env": {}
       }
     }
   }
   

   sonilo login でサインインしている場合、設定はこれですべてです。キーを設定する場合や、デフォルト値を変更する場合は、以下のようにします。

   "env": {
     "SONILO_API_KEY": "sk-...",
     "SONILO_API_URL": "https://api.sonilo.com",
     "TIME_OUT_SECONDS": "600"
   }
   

4. Claude Desktop を再起動します。 ツールメニューに Sonilo のツールが表示されます。

Codex ですぐに始める

CLI（npm install -g sonilo-cli && sonilo login）でサインインしている場合、セットアップは次の 1 つのコマンドで完了します。

codex mcp add sonilo -- uvx sonilo-mcp

または、自分でキーを設定する場合：

codex mcp add sonilo --env SONILO_API_KEY=sk-... -- uvx sonilo-mcp

手動で設定する場合：

1. Sonilo dashboard からAPI キーを取得します — sonilo login でサインインしている場合は、この手順を省略できます。

2. uv パッケージマネージャーをインストールします（uvx が含まれています）。

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. **Codex > Settings > MCP servers を開き、以下を入力します。

または、サーバーを追加するには ~/.codex/config.toml に次の内容を記述します。

[mcp_servers.sonilo]
command = "uvx"
args = ["sonilo-mcp"]

# Omit this whole block when you have signed in with `sonilo login`.
[mcp_servers.sonilo.env]
SONILO_API_KEY = "sk-..."
SONILO_API_URL = "https://api.sonilo.com"
TIME_OUT_SECONDS = "600"

4. Codex を再起動する（または新しいセッションを開始する）と、/mcp を実行して sonilo が接続され、ツールが一覧表示されていることを確認できます。

使用例

サーバーが接続されたら、アシスタントに自然な言葉で依頼してください。たとえば：

• 「この動画に合うバックグラウンドミュージックを作成してください：~/Desktop/promo.mp4。」
• 「https://example.com/clip.mp4 に、落ち着いたアンビエントスタイルの音楽を付けてください。」
• 「AI で生成したクリップをつないで ~/Desktop/trailer.mp4 にしました。編集に合うサウンドトラックを追加してください。」
• 「Sonilo mcp を使って、勉強用プレイリスト向けに軽快なローファイ・ヒップホップを 30 秒分生成し、デスクトップに保存してください。」
• 「Sonilo を使って、壮大なオーケストラ調のシネマティックトラックを約 60 秒で作成してください。」
• 「自分のアカウントで利用できる Sonilo のサービスと制限を教えてください。」
• 「過去 7 日間の Sonilo の使用状況を表示してください。」
• 「今生成したトラックを再生してください。」

アシスタントは該当するツール（text_to_music、video_to_music、text_to_sfx、video_to_sfx、audio_ducking、get_sfx_task、get_account_services、get_usage、または play_audio）を呼び出し、生成した音声を設定済みの出力ディレクトリに保存します。

設定

認証

サーバーは、SONILO_API_KEY が設定されていればその値をキーとして使用し、設定されていない場合は sonilo login で書き込まれた認証情報（~/.config/sonilo/credentials.json または $XDG_CONFIG_HOME/sonilo/）を使用します。環境変数が優先されるのは意図的な仕様です。そのため、すでに環境変数を設定している構成では、アップグレード後も同じアカウントが引き続き使われます。

認証情報は、サーバー自身の SONILO_API_URL に基づいて検索されるため、ステージングサーバーが本番環境のサインイン情報を取得することはありません。このサーバーがファイルに対して行うのは読み取りのみです。認証情報を更新するには sonilo login を再実行してください（サインインで発行されたキーの有効期限は 90 日です）。認証を無効にするには sonilo logout を実行してください。

環境変数

変数	デフォルト	説明
SONILO_API_KEY	(from sonilo login)	Bearer トークンです。CLI にサインインしていない場合にのみ必要です。
SONILO_API_URL	https://api.sonilo.com	公開 API のベース URL です。
SONILO_MCP_BASE_PATH	~/Desktop	デフォルトの出力ディレクトリであり、相対入力パスの基準です。また、アクセス制限の境界でもあります（以下を参照）。
SONILO_MCP_ALLOW_ANY_PATH	false	true に設定すると、ツールが SONILO_MCP_BASE_PATH の外にあるファイルを読み書きできるようになります。
TIME_OUT_SECONDS	600	音楽のストリーミング（preserve_speech を指定しない text_to_music および video_to_music）、アップロード、ダウンロードのタイムアウト（秒）です。バックエンドのストリーミング読み取りタイムアウトに合わせています。タスクベースのツール（効果音、ダッキング、video-to-video、非同期音楽、analyze_video、proofread）は、バックエンドのキューでタスクが最大 2400 秒待機するため、設定値にかかわらず、タスクの完了を少なくとも 2700 秒（45 分）待ちます。さらに長く待つには、この値を大きくしてください。stems は少なくとも 75 分、ダビングは少なくとも 2 時間待ちます。

一部の MCP ホストには独自のツール呼び出しタイムアウトがあり、待機時間が終わる前に呼び出しが打ち切られる場合があります。タスクは実行され続け、課金も発生します。タスク ID はサーバーの標準エラーログに [sonilo-mcp] task submitted: <id> として記録され、get_sfx_task("<id>") で結果を取得できます。結果が失われることはありません。

ファイルアクセスとアクセス制限

デフォルトでは、ファイルツール（video_to_music の入力、play_audio、および任意の output_directory）は SONILO_MCP_BASE_PATH の範囲内に制限されます。シンボリックリンクの解決後にこの範囲外となるパスは拒否されます。これにより、クライアントがだまされて任意のファイルを読み取ったり、外部に持ち出したりする場合の被害範囲を抑えられます。この制限を解除するには（たとえば、ディスク上の別の場所にある動画を読み込む場合）、SONILO_MCP_ALLOW_ANY_PATH=true を設定してください。

ツール

ツール	説明	料金
text_to_music(prompt, duration?, output_format?, variants_num?, stems?, output_directory?)	テキストプロンプトから音楽を生成します。variants_num（1～10、デフォルトは1）を指定すると、1回のリクエストでその数の異なるバリエーションを生成し、それぞれに固有のタイトルが付きます。N > 1 の場合、バックエンドの非同期モードが自動的に強制され、無料トライアルの対象にはなりません。stems（デフォルトはfalse）を指定すると、追加料金なしでトラックをドラム、ベース、ボーカル、その他の4つの個別の楽器トラックに分割して保存します。処理に数分追加でかかり（呼び出しは最大75分待機します）、バックエンドの非同期モードが自動的に強制されます。結果にstems_errorの注記がある場合、無料の分離処理に失敗したか、スキップされたことを意味します。音楽自体には問題ありません。	✅
video_to_music(video_path? | video_url?, prompt?, preserve_speech?, variants_num?, prompt_influence?, stems?, output_directory?)	動画に合った音楽を生成します。最大長は360s（6 min）で、アカウントのアップロードサイズ上限（通常300 MB）の対象です。preserve_speech（デフォルトはfalse）を指定すると、元の音声の会話を結果に残します。vocalsの会話ステムと、そのまま使えるミックス済みファイルも取得できます。この設定を有効にすると、ストリーミングの代わりにバックエンドの非同期生成モードで内部処理されます。variants_num（1～10、デフォルトは1）の動作はtext_to_musicと同じです。prompt_influence（0～1、APIのデフォルトは0.5）は、生成される音楽がプロンプトにどの程度従うかを設定します。プロンプトへの追従を強めたり弱めたりしたい場合を除き、省略してください。無料で、ストリーミングモードと非同期モードの両方で動作します。stems（デフォルトはfalse）の動作はtext_to_musicと同じです。分割されるのは生成された音楽であり、動画自体の音声ではありません。	✅
text_to_sfx(prompt, duration?, audio_format?, output_directory?)	テキストから効果音を生成します。長さは0.5～180sで、省略可能です。省略するとSonilo独自のデフォルトの長さが使われます。形式はwav/mp3/aac/flac（デフォルトはaac）です。	✅
video_to_sfx(video_path? | video_url?, prompt?, segments?, audio_format?, output_directory?)	動画用の効果音を生成し、生成した効果音の音声を保存します。動画の最大長は**480s（8 min）**です。	✅
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=trueを渡すと、音楽を元のトラックの下に一定の音量でミックスして、元のトラック全体を残します。代わりに音声の下で音楽の音量を下げるには、ducking=trueを追加します。分離した会話のみを残すには、preserve_speech=trueを指定します。keep_original_soundはpreserve_speechより優先されます。入力にはH.264/HEVC/VP9/AV1（mp4、mov、m4v、webm）が必要です。アニメーションgifとVP8 webmは拒否されます。動画の最大長は**360s（6 min）**です。variants_num（1～10、デフォルトは1）を指定すると、バリエーションごとに.mp4を1つ保存します。prompt_influence（0～1、APIのデフォルトは0.5）は、生成される音楽がプロンプトにどの程度従うかを設定します。プロンプトへの追従を強めたり弱めたりしたい場合を除き、省略してください。無料です。	✅
video_to_video_sfx(video_path? | video_url?, prompt?, segments?, output_directory?)	動画用の効果音を生成し、効果音をミックスした新しい.mp4を返します。動画の最大長は**480s（8 min）**です。	✅
video_to_sound(video_path? | video_url?, music_prompt?, sfx_prompt?, segments?, preserve_speech?, ducking?, output_format?, variants_num?, output_directory?)	1回の呼び出しで動画用の音楽と効果音を生成し、ミックス済みの音声トラックを保存します。料金は2回分ではなく1回分で、2つのレイヤーはバックエンドでバランス調整されます。ducking（デフォルトはfalse）を指定すると、元の動画の会話音声をミックスに加え、その下で音楽の音量を下げます。オフのままにすると、結果は生成された音楽と効果音のみになり、music_processedステムはありません。output_format（デフォルトはwav、またはm4a、320 kbpsのmp3）でミックス済みトラックのコンテナを設定します。音楽と効果音のステムは元の形式のままです。動画の最大長は**480s（8 min）**です。variants_num（1～10、デフォルトは1）を指定すると、バリエーションごとにミックス済みトラックを1つ保存します。	✅
video_to_video_sound(video_path? | video_url?, music_prompt?, sfx_prompt?, segments?, keep_original_sound?, preserve_speech?, ducking?, variants_num?, output_directory?)	video_to_soundと同様ですが、ミックス済みのサウンドトラックを入れた新しい.mp4を返します。デフォルトでは、結果の音声は生成された音楽と効果音のみで、元の音声は削除されます。そのため、結果にはmusic_processedステムもありません。keep_original_sound=trueを渡すと、元のトラック全体を残します（一定の音量でミックスされます。代わりにミックス音声の下で元のトラックの音量を下げるには、ducking=trueを追加します）。分離した会話のみを残すには、preserve_speech=trueを指定します。keep_original_soundはここでのみ使用でき、video_to_soundでは使用できません。動画の最大長は**480s（8 min）**です。variants_num（1～10、デフォルトは1）を指定すると、バリエーションごとに.mp4を1つ保存します。	✅
dubbing(video_path? | video_url?, languages?, ducking?, lipsync?, subtitles?, export_srt?, output_directory?)	動画を他の言語に吹き替え、言語ごとに吹き替え済みの.mp4を1つ保存します。languagesにはコードのリストを指定します（en、zh_cn、ja、ko、pt、pt_br、es、es_419、de、fr、it、ru、th、ar、tr、vi、id、ta、ml、kn、gu、pa_in、sd_in、hi）。省略すると、デフォルトの["zh_cn", "es", "fr"]が使われます。pt_brはブラジルポルトガル語、es_419はラテンアメリカのスペイン語です。単独のptとesは地域を指定せず、arも同様です。pa_inとsd_inはインドで話されるパンジャブ語とシンド語で、使用できるのはこれらのバリエーションのみです。hiはヒンディー語です。video_urlにはhttpsを指定する必要があります。吹き替えのパイプラインがソースを直接取得するためです。lipsyncのデフォルトはtrueです。話者の口元が吹き替え音声に合うよう再描画されます。映像を一切変更しない場合はlipsync=falseを設定します。その場合、動画は再描画されず元の解像度とフレームレートで返され、音声のみが置き換えられるため、口の動きは元の言語のままです。カメラに映る話者がいない映像に便利です。subtitlesには対象言語ごとに1つの台本を指定します。たとえば{"es": "/path/es.srt", "fr": "https://.../fr.vtt"}のように、ローカルの.srt/.vttパスまたはhttps URLを指定し、その言語で読み上げる台詞を記述します。パイプライン独自の翻訳の代わりに使用されます。キーは吹き替え対象の言語と一致している必要があります。export_srt（subtitlesが必要）を指定すると、納品された音声に合わせてタイミングを調整し、台詞をそのまま保持した.srtも言語ごとに返します。動画の最大長は300s（5 min）です。言語ごとに課金されます。subtitlesなしで最初に行う単一言語の呼び出しは、15秒間の無料プレビューです（下記の無料トライアルを参照）。	✅
proofread(video_path? | video_url?, languages?, source_language?, output_directory?)	動画を書き起こし、台本を対象言語に翻訳して、言語ごとに編集可能な.srtを1つと、ソース言語の書き起こしを保存します。吹き替えや読み上げは行われません。dubbingの前のステップとして、文言を修正してからファイルをsubtitlesとしてdubbingに渡します。languagesにはdubbingと同じコードを指定します。省略するか[]を渡すと、ソース言語の書き起こしのみが作成されます。source_languageは書き起こしに使う任意のヒントです。省略すると言語が検出され、どちらの場合も検出されたコードが報告されます。video_urlにはhttpsを指定する必要があり、動画には音声トラックが必要です。動画の最大長は**300s（5 min）**です。言語ごとに課金されます（書き起こしのみのリクエストは1言語分としてカウントされます）。課金の最小単位は10秒です。	✅
analyze_video(video_path? | video_url?, prompt?, variants_num?, mode?)	動画を分析してクリエイティブブリーフを返します。時間に沿ったsegmentsのプランと、各バリエーション用のすぐに使える生成promptが含まれます。modeのデフォルトはbothで、音楽のブリーフに加えてサウンドデザインのブリーフ（sfx_segmentsと単一のsfx_prompt）も返します。musicまたはsfxを指定すると、同じ料金でそのブリーフのみを返します。何も生成せず、ファイルも書き込みません。ブリーフはJSONとしてインラインで返され、そのままvideo_to_music、video_to_sfx、video_to_sound、またはそれらに対応するvideo-to-videoツールに渡せます。動画をどのような音にすべきかまだわからない場合に使用します。動画の最大長は**480s（8 min）**です。variants_numは1～5（デフォルトは1）で、ブリーフごとに課金されます。課金の最小単位は10秒です。	✅
audio_ducking(voice_path? | voice_url?, music_path? | music_url?, output_directory?)	音声トラックの下で音楽の音量を下げます。音声入力には動画も指定でき、その場合、音量を調整したミックスが新しい.mp4にミックスされます。各入力の最大長は**360s（6 min）**で、アカウントのアップロードサイズ上限の対象です。	✅
get_sfx_task(task_id, output_directory?)	効果音、オーディオダッキング、動画から動画への変換、動画からサウンドへの変換、吹き替え、校正、動画分析、または非同期の動画から音楽への変換のタスクを確認して結果を返します。タイムアウトしたtext_to_sfx、video_to_sfx、audio_ducking、video_to_video_music、video_to_video_sfx、video_to_sound、video_to_video_sound、dubbing、proofread、analyze_video、video_to_music(preserve_speech=true)の呼び出しから復旧するために使用します。analyze_videoのタスクにはダウンロードするファイルがないため、ブリーフはインラインで返されます。proofreadのタスクでは直接呼び出した場合と同様に.srtファイルが保存されます。それ以外はすべてディスクに保存されます。	❌
get_account_services()	利用可能なサービス、上限、サービスごとの無料トライアルの残り利用枠を一覧表示します。	❌
get_usage(days=30)	利用状況の概要と日ごとの内訳を表示します。	❌
play_audio(input_file_path)	ローカルの音声ファイルを再生します。	❌
✅ が付いたツールは、Sonilo アカウントで料金が発生する API 呼び出しを行います。

すべてのツールには MCP ツールアノテーションも付いているため、クライアントは説明を読まずにこの 2 種類を見分けられます。get_account_services、get_usage、play_audio は読み取り専用です。それ以外のツールはすべてファイルを書き込むか料金が発生しますが、破壊的な操作を行うものはありません（出力によって既存のファイルが上書きされることはありません）。サーバーの instructions では、エージェントに対して、最初の有料呼び出しの前に get_account_services を確認し、タイムアウトした呼び出しは get_sfx_task で復旧するよう指示しています。

無料トライアル： セルフサービスのアカウントでは、各サービスを数回無料で実行できます。カードの登録は不要です。get_account_services() は、残り回数を trial[service] = {granted, used, remaining} として返します。✅ ツールを呼び出す前に確認し、ユーザーに警告して、呼び出しが失敗するのを防いでください。サービスの remaining が 0 になると、支払い方法が追加されるまで、そのサービスの呼び出しは trial_exhausted で失敗します。吹き替えの無料実行は 1 回で、15 秒のプレビューです。字幕なしで最初に単一言語を指定して呼び出すと、動画の最初の 15 秒だけが無料で翻訳され、結果には動画全体の料金を示す trial_preview が含まれます。proofread は 2 回まで無料で、吹き替えと同様に言語ごとに課金されます。無料トライアルの対象外のアカウントには、trial キーがありません。

任意： ffprobe（FFmpeg の一部）がインストールされている場合、video_to_music は動画の長さをローカルで確認し、360s を超えるファイルをアップロード前に拒否します。video_to_sfx も同様に、上限を 480s としてローカルで確認します。audio_ducking は、2 つの入力の長さをそれぞれ上限 360s と照合して同じ確認を行います。ffprobe がない場合でも、同じ制限がバックエンドで適用されます。

効果音とダッキングはタスクとして実行されます

音楽ツールは結果をストリーミングし、1 回の呼び出しで完了します。ただし、例外として video_to_music(preserve_speech=true) は タスク を送信し、内部でポーリングします。元の音声を保持できるのは、バックエンドの非同期モードのみだからです。単一の呼び出しで保存済みファイルのパスが返されるため、タスクを目にすることはありません。また、SFX ツールと同様に、呼び出しがタイムアウトした場合は同じ get_sfx_task の復旧方法を使用します。SFX ツールは タスク を送信し、完了するまでポーリングします。text_to_sfx と video_to_sfx はこれを自動で行い、保存済みファイルのパスを返すため、通常はタスクを目にすることはありません。audio_ducking も同じ送信後にポーリングする流れと、同じ get_sfx_task の復旧方法を使用します。

呼び出しがタイムアウトしても、生成は実行され続け（料金もすでに発生しています）。エラーメッセージにはタスク ID が含まれ、準備ができたら get_sfx_task("<id>") で結果を取得できます。タスク ID は、タスクの送信時に標準エラー出力にも表示されるため、呼び出しがキャンセルされても確認できます。get_sfx_task は繰り返し呼び出しても安全です。ファイルがすでにディスク上にある場合は、2 回目のダウンロードを行わず、そのことを報告します。

出力形式

音楽は .m4a（MP4 コンテナ内の AAC）として保存されます。ファイル名にはバックエンドから返されたタイトル（スラッグ化したもの）を使用し、タイトルがない場合は sonilo-<timestamp>.m4a を使用します。複数のストリームが並行して返される場合は、-<index> のサフィックスが追加されます。

video_to_music(preserve_speech=true) は、最大 3 種類のファイルを保存します。各ファイルは返されるテキストに記載されます。生成された音楽音声（上記と同じ命名規則で、prompt を使用し、ない場合は music-<first 8 chars of the task id> を使用）、保持された音声のステムである <base>-vocals.<ext>、そしてミックス音声（音声と音楽をすでにミックスした、そのまま使える結合済みの結果）である <base>-mux.<ext>（複数のストリームがある場合は <base>-mux-<index>.<ext>）です。音声ステムとミックス音声の拡張子は、バックエンドから報告される content_type に基づきます（通常は .m4a）。

効果音は、指定された audio_format（wav、mp3、flac、またはデフォルトの aac。デフォルトは .m4a として書き込まれます）で保存されます。video_to_sfx が保存するのは音声のみで、元の動画は保存されません。 サウンドの結合（video_to_sound / video_to_video_sound）は、単一のファイルとして保存されます。video_to_sound では .wav、video_to_video_sound では .mp4 になります。名前には music_prompt が使われ、指定されていない場合は sfx_prompt、それも指定されていない場合は sound-<first 8 chars of the task id> / v2v-sound-<first 8 chars of the task id> が使われます。音楽とSFXの個別のステムはバックエンドに残り、ダウンロードされるのはミックス済みの結果のみです。

複数のバリエーション（text_to_music / video_to_music / video_to_video_music / video_to_sound / video_to_video_sound で variants_num > 1 の場合）は、1つではなくバリエーションごとにファイルを保存し、リクエスト順に -0、-1、…を付加します（例：<base>-0.m4a、<base>-1.m4a）。音楽ツールでは、各バリエーションがそれぞれ独自のクリエイティブな方向性を持ち、バックエンドがタイトルを返す場合は、返されるテキストにそのバリエーション名が記載されます。料金は variants_num に比例して増加し、無料トライアルアカウントでも、1を超える値を指定すると全額が請求されます。タイムアウトした複数バリエーションの呼び出しも、単一バリエーションの場合と同様に、すべてのバリエーションを get_sfx_task で復旧できます。

ステム（text_to_music / video_to_music で stems=true の場合）は、生成されたストリームごとに追加のファイルを4つ保存します。<base>-stems-drums.<ext>、-stems-bass、-stems-vocals、-stems-other です（variants_num > 1 の場合、バリエーションのインデックスを含めて <base>-stems-<index>-<name>.<ext> になります）。元のフルトラックもそのまま保存されます。分離は無料で、最善努力で実行されます。通常は2～6分追加されます（呼び出しは最大40分待機します）。失敗した場合やスキップされた場合、音楽自体には影響せず、完全に提供されますが、結果にはステムファイルの代わりに、または一部のステムファイルとともに、stems_error の注記が含まれます。

吹き替え（dubbing）は、リクエストした言語ごとに1つの .mp4 として保存され、ファイル名は dubbing-<first 8 chars of the task id>.<language>.mp4 になります。ファイル名を指定するプロンプトはありません。export_srt を指定すると、各言語のタイミングを調整したスクリプトが動画と同じ場所に dubbing-<first 8 chars of the task id>.<language>.srt として保存され、その言語のエクスポート状況とアラインメントの損失が報告されます（エクスポートがブロックされた場合は、問題コードとレポートへのリンクも含まれます）。すべての吹き替え済み .mp4 は、最初の .srt より先にダウンロードされます。ブロックされた、またはダウンロードできなかったスクリプトは失敗ではなく注記として報告されるため、字幕がなくても動画が失われることはありません。4つの言語を指定すると、4つのファイルが作成され、料金は1言語の場合の4倍になります。吹き替えのポーリングは、TIME_OUT_SECONDS に関係なく最低2時間続きます。これはジョブに対するバックエンド独自の上限に合わせたものです。

校正（proofread）は、結果内で言語ごとに1つの .srt として保存され、ファイル名は proofread-<first 8 chars of the task id>.<language>.srt になります。ファイル名を指定するプロンプトはありません。ファイル一式には、リクエストしたすべての対象言語に加えて、検出されたソース言語が必ず含まれるため、languages を指定しないリクエストでも1つのファイルが作成されます。ファイルの後に、返されるテキストには検出された source_language とソーススクリプトの cue_count が記載され、その後にブロック対象ではない警告ごとの注記（例：読み取るには表示時間が短すぎるキュー）が続きます。警告によってファイルがブロックされることはありません。また、.srt をダウンロードできなかった言語は、失敗ではなくタスクIDを含む注記として報告されます。ファイルを編集した後、承認済みの文言で吹き替えを行うには、subtitles として dubbing に渡してください。吹き替えでは字幕のキーが吹き替え対象の言語と一致する必要があるため、ソース言語自体が対象言語でない限り、ソース言語のファイルは含めないでください。

ファイル名にはプロンプトの内容が使われます（スラッグ化され、80文字に切り詰められます）。ファイル名を指定するプロンプトがない場合（プロンプトなしの video_to_sfx、または get_sfx_task で復旧したSFX / ダッキングのファイル）、名前は代わりに sfx-<first 8 chars of the task id> になります。get_sfx_task で復旧した video_to_music(preserve_speech=true) タスクの名前は、代わりに music-<first 8 chars of the task id> になります（get_sfx_task は音楽エンベロープの形状を検出し、直接の video_to_music 呼び出しと同じ方法でオーディオ / ボーカル / 多重化を保存します）。既存のファイルが上書きされることはありません。代わりに -1、-2、…のサフィックスが追加されます。 ダッキングの結果は、単一のファイルとして保存されます。.wav、または音声入力が動画の場合は .mp4 です（ダッキングしたミックスは動画に再多重化されます）。ファイル名は音声入力の名前に -ducked を付けたものです（例：interview.mp4 → interview-ducked.mp4）。使用可能な名前がない場合は、ducked-<タスク ID の先頭 8 文字> になります。get_sfx_task で取得したダッキングの結果は、参照できる音声ファイル名がないため、代わりに sfx-<タスク ID の先頭 8 文字> という名前になります。

よくあるエラー

メッセージ	対処方法
SONILO_API_KEY not set and no stored credential found	sonilo login を実行するか、サーバーの設定で SONILO_API_KEY を設定してください。
Invalid SONILO_API_KEY	https://platform.sonilo.com/dashboard/api-keys でキーを確認してください。CLI でサインインした場合、キーの有効期限（90 日）が切れたか、取り消された可能性があります。もう一度 sonilo login を実行してください。
Insufficient minutes / Credit limit exceeded	https://platform.sonilo.com/dashboard/billing でチャージしてください。
You've used your N free trial calls for <service>	このサービスの無料トライアル枠を使い切っています。https://platform.sonilo.com/dashboard/billing で支払い方法を追加してください。再試行しても解決しません。get_account_services で、他のサービスの残りを確認できます。
Rate limit exceeded: your account allows N requests per minute	呼び出しの間隔が短すぎます。カウンターは固定の 60 秒間隔で動作し、拒否された呼び出しもカウントされるため、間隔内に再試行せず、ウィンドウが終わるまで待ってください。get_account_services で rpm_limit を確認できます。上限の引き上げを希望する場合は、[email protected] までメールでお問い合わせください。
Too many concurrent generations: N of N in progress	すべての生成枠が使用中です。待つだけでは枠は空きません。実行中の生成が完了する必要があります。get_account_services で concurrency_limit を確認できます。上限の引き上げを希望する場合は、[email protected] までメールでお問い合わせください。
Generation timed out（音楽、preserve_speech を指定しない text_to_music／video_to_music）	TIME_OUT_SECONDS を引き上げてください。get_usage でバックエンドの処理が完了し、課金されたかどうかを確認してください。
Timed out … waiting for task <id>（SFX、ダッキング、または video_to_music(preserve_speech=true)）	生成はまだ実行中です。get_sfx_task("<id>") を呼び出して結果を取得してください。タイムアウトした preserve_speech 音楽タスクも含め、結果は失われません（get_sfx_task は結果の形式を認識し、video_to_music と同じ方法で音声／ボーカルの保存や多重化を行います）。
Task not found	タスク ID が存在しないか、純粋なストリーミング生成（text_to_music、または preserve_speech を指定しない video_to_music）に属しています。この種の生成はポーリングできません。ID を確認してください。