setup-api-key

Sonilo のセットアップ

ユーザーが Sonilo に接続できるよう案内します。接続方法はいくつかあります。最初に記載されているものを選ぶのではなく、ユーザーが実際に何をしようとしているかに応じて選んでください。

方法	API キーが必要ですか？	最適な用途
A. sonilo login（CLI サインイン。ローカル MCP サーバーと認証情報を共有）	いいえ — ブラウザーで OAuth を使用	ブラウザーを使えるマシンを利用しているすべてのユーザー。1 回サインインすれば、CLI と uvx sonilo-mcp の両方で利用できるため、MCP の設定にシークレットを含める必要がありません。
B. リモート OAuth MCP プラグイン（sonilo-claude-plugin、またはこのリポジトリの Muse Code プラグイン）	いいえ — OAuth サインイン	ローカルで何も実行したくない Claude Code および Muse Code のユーザー。すべてのツールを利用できます。
C. API キー（SONILO_API_KEY）	はい	CI、コンテナー、ヘッドレス環境、キーを自分で管理したいユーザー。すべてのクライアントで動作します。

選び方：

• ブラウザーを使えるマシンで、任意の MCP ホストを利用する場合 → 方法 A。最短の手順で、設定ファイルにシークレットを残しません。
• Claude Code または Muse Code を利用していて、ローカルで何も実行したくない場合 → 方法 B。
• ブラウザーが使えない（CI、コンテナー、リモートマシン）場合、またはユーザーがすでにキーを持っていると言った場合 → 方法 C。
• エージェントをまったく使わずに作業する場合（コードの作成、シェルスクリプトの実行など） → 末尾の方法 D。方法 A〜C の MCP 設定は適用されません。

ステップ 0：すでに動作しているものがないか確認する（すべての方法）

何かを変更する前に実行してください。多くの場合、「何もする必要がない」という結果になります。

トランスポートは 2 種類あり、どちらか一方が動作すれば十分です。何も設定されていないと判断する前に、両方を確認してください。

1. MCP： sonilo MCP サーバーが接続されていますか（text_to_music や get_account_services など、任意の Sonilo ツールを呼び出せる状態ですか）？接続されている場合は、無料で読み取り専用の get_account_services() を呼び出します。
2. CLI： Sonilo ツールがない場合は、sonilo account を実行します。これは上記と同じ、無料の読み取り専用呼び出しです。終了コード 0 は、CLI がインストールされ、サインイン済みで、API に接続できることを意味します。これでスキルから直接操作できます。**sonilo whoami で確認しないでください。**サインアウト中でも終了コード 0 を返すため、両方の状態を区別できません。また、表示名のないアカウントでは account: の行が空になり、認証情報が壊れているように見えます。このコマンドを実行する価値があるのは、どのアカウントがアクティブかを表示する場合だけであり、状態の判定には使用しないでください。
3. どちらか一方が成功： Sonilo は設定済みで、動作しています。そのことを伝えて終了してください。確認するのは、認証情報をローテーションしたいかどうかだけにしてください。
4. 401 エラー： 認証情報がないのではなく、古くなっています。sonilo login でサインインした場合は、キーの有効期限切れ（90 日）または失効が原因の可能性があります。再度 sonilo login を実行すれば解決します。それ以外の場合はキーに誤りがあります。方法 C に進んでください。
5. どちらも応答しない： 何も接続されていません。以下から方法を選び、実行してください。MCP の方が適しています（シェルが不要で、吹き替えジョブの 2 時間のポーリング中も利用できる唯一のトランスポートです）。ただし、インストール済みでサインインも済んでいる CLI だけでも完全なセットアップです。利用する予定のない MCP を設定させないでください。

キーや認証情報ファイルの内容を、表示、引用、エコーしないでください。言及が必要な場合は、必ず伏せ字にしてください。

パス A：sonilo login（API キー不要、すべての MCP ホストに対応）

一度サインインすれば、CLI とローカル MCP サーバーの両方が認証されます。CLI は認証情報を ~/.config/sonilo/credentials.json に書き込み、sonilo-mcp（0.16.0 以降）がそれを読み取ります。

npm install -g sonilo-cli     # or: pip install sonilo-cli
sonilo login

CLI はワンタイムコードを表示し、ブラウザーで platform.sonilo.com を開きます。ユーザーは Sonilo Platform アカウント（一般向けの sonilo.com アカウントとは別）にサインインし、コードがターミナルに表示されたものと一致することを確認して、承認します。ブラウザーのないマシンでは、--no-browser を追加し、別のデバイスから表示された URL を開いて承認してもらいます。

次に、設定にシークレットを含めずに MCP サーバーを追加します。

claude mcp add sonilo -- uvx sonilo-mcp     # Claude Code
codex mcp add sonilo -- uvx sonilo-mcp      # Codex

Claude Desktop の設定全体は次のとおりです。

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

どちらにも uv パッケージマネージャー（uvx を提供）が必要です。brew install uv（macOS）、pipx install uv／pip install uv、または winget install --id=astral-sh.uv（Windows）でインストールします。その他の方法については、https://docs.astral.sh/uv/getting-started/installation/ をご覧ください。

あらかじめユーザーに伝えておくとよいこと：

• 承認すると、ユーザーのアカウントに cli: <hostname> という名前の通常の API キーが発行されます。このキーは 90 日後に有効期限が切れ、https://platform.sonilo.com/dashboard/api-keys で確認および失効できます。
• sonilo whoami でアクティブなアカウントと認証情報の取得元を確認できます。sonilo logout はサーバー側でキーを失効させてから、ローカルに保存されたキーを削除します。
• エクスポートされた SONILO_API_KEY はサインインより優先されます。 ツールが予期しないアカウントで認証される場合は、まずこの環境変数を確認してください。設定されている場合は、そのことが sonilo whoami に明示されます。
• サインインは人間向けです。プロビジョニング済み／POC アカウントには Sonilo がキーを発行するため、これらのユーザーは sonilo login を利用できません。パス C を案内してください。

ステップ 0 とまったく同じように、get_account_services() で検証します。

パス B：リモート OAuth プラグイン（Claude Code または Muse Code、API キー不要）

claude
/plugin marketplace add sonilo-ai/sonilo-claude-plugin
/plugin install sonilo@sonilo

最初の Sonilo ツール呼び出しでブラウザーが開き、Sonilo Platform アカウント（platform.sonilo.com。一般向けの sonilo.com アカウントとは別）にサインインして、アクセスを承認します。Claude Code は取得したトークンをユーザーごとに OS のキーチェーンへ保存するため、コピー、貼り付け、設定は不要です。いつでも /mcp から確認または接続解除できます。

この方法では、ホストされた単一のエンドポイント（https://api.sonilo.com/mcp、OAuth 2.1 + PKCE）に接続します。このエンドポイントは、ローカルサーバー（パス A および C）と同じツールセットを提供します。テキストまたは動画からの音楽／効果音生成、動画から動画への音楽／効果音生成、動画からサウンドへの変換、動画から動画サウンドへの変換、吹き替え、オーディオのダッキング、アカウント／使用状況の確認に対応しています。ほかの MCP ホストを使う場合や、自分のキーを保持・管理したいユーザーには、引き続きパス A または C が適しています。

Muse Code： Sonilo スキルプラグインには同じホスト型サーバーが含まれているため、インストールするだけでセットアップは完了します。

MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins marketplace add sonilo-skills https://github.com/sonilo-ai/skills
MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins install skills@sonilo-skills
MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins approve skills

approve を実行すると MCP サーバーが有効になります（Muse はサードパーティ製プラグインのサーバーを、承認するまで無効にしています）。最初の Sonilo ツール呼び出しで、同じ Sonilo Platform へのサインインが求められます。呼び出し時にサーバーで OAuth サインインが必要だと表示された場合は、~/.config/muse/settings.json に "mcp_servers": {"sonilo": {"transport": "streamable_http", "url": "https://api.sonilo.com/mcp"}} を追加し、muse mcp login sonilo を実行してください。Muse Code 1.4.0 は、そこに記載されたサーバーにのみサインインします。

パス C：API キー（CI、コンテナー、またはユーザーの希望による場合）

ステップ 1：API キーを取得する

パス A が適さない場合（ブラウザーがない、プロビジョニング済みアカウントを使用する、CI で使う、またはキーの保持を希望する場合）に限り、この方法を使います。ユーザーには次のように伝えてください。

ダッシュボードから Sonilo API キーを取得してください：https://platform.sonilo.com/dashboard/api-keys

（アカウントが必要ですか？ まずそちらで登録してください。セルフサービスアカウントでは、ほとんどのエンドポイントでカード不要の無料生成を数回利用できます。）

キー（sk-... のような形式）を取得したら、教えてください。こちらで接続します。可能であれば、このチャットに直接貼り付けないでください。代わりに MCP サーバーの設定に組み込みます。

Step 2: MCP サーバーに接続する

ユーザーがキーを取得したら、それを使って sonilo MCP サーバーに接続します。ホストが対応している場合は、CLI 形式を優先してください。

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

その CLI に対応していないホスト（Claude Desktop、Codex）では、MCP 設定を直接編集します。

Claude Desktop（claude_desktop_config.json）：

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

Codex（~/.codex/config.toml）：

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

[mcp_servers.sonilo.env]
SONILO_API_KEY = "sk-..."

どちらも uv パッケージマネージャー（uvx を提供）が必要です。まだインストールされていない場合は、brew install uv、pipx install uv / pip install uv、または winget install --id=astral-sh.uv を使用してください（その他の方法については、https://docs.astral.sh/uv/getting-started/installation/ を参照してください）。設定ファイルを直接編集した後は、ホストアプリ（Claude Desktop/Codex）を再起動するようユーザーに伝えてください。Claude Code で claude mcp add を実行した場合は、再起動しなくても次のセッションから反映されます。

Step 3: 検証する

接続後、get_account_services() を呼び出します。

• 成功した場合： Sonilo が設定され、動作していることを確認します。get_account_services() では、サービスごとに無料トライアルの残り実行回数も確認できることを伝えます。
• 失敗した場合（401）： 認証情報が間違っています。この手順ではキーが無効ということなので、Step 1 のダッシュボードリンクを案内し、正しいキーを用意してもらいます。ユーザーが代わりに sonilo login でサインインした場合は、そのサインインで使用したキーの有効期限が切れているか、取り消されています。もう一度 sonilo login を実行します。
• Sonilo のツールがまったく表示されない場合： MCP サーバー自体が接続されていません。Step 2 の設定ファイルの場所を再確認し、ホストが再起動または再読み込みされたことを確認します。

Path D: Python/JS SDK または CLI（MCP なし）

すべての連携が MCP ホスト経由とは限りません。ユーザーがコードを書いている場合や、シェルからスクリプトを実行している場合は、次のようにします。

pip install sonilo          # Python SDK
npm install sonilo          # JS/TS SDK
pip install sonilo-cli      # Python-distributed CLI
npm install -g sonilo-cli   # npm-distributed CLI

Path C と同じ API キーを使用します。https://platform.sonilo.com/dashboard/api-keys からキーを取得し、環境変数 SONILO_API_KEY に設定します（両方の SDK と両方の CLI が自動的に読み取るため、MCP 設定、claude mcp add、プラグインのインストールは不要です）。SDK 独自のアカウント呼び出し（client.account.services() / sonilo.account.services()）または CLI の sonilo account で検証します。

オプションの設定（ローカル MCP サーバー）

ユーザーの目的に関係する場合にのみ、これらについて説明してください。どれも妥当なデフォルト値が設定されています。

変数	デフォルト値	説明するタイミング
SONILO_API_URL	https://api.sonilo.com	デフォルト以外のデプロイを使用する場合のみ。
SONILO_MCP_BASE_PATH	~/Desktop	生成ファイルのデフォルトの保存先であり、相対入力パスの基準にもなります。ユーザーが別の場所に出力したい場合は、変更を提案します。
SONILO_MCP_ALLOW_ANY_PATH	false	ユーザーが SONILO_MCP_BASE_PATH の外にあるファイルを読み書きする必要がある場合に限り、true に設定します。提案する前に、これによってツールのファイルシステムへのアクセス範囲が広がることを説明してください。
TIME_OUT_SECONDS	600	ストリーミング音楽、アップロード、ダウンロードのリクエストごとのタイムアウトです。タスクベースのツール（SFX、サウンド、ダッキング、非同期音楽）は、タスクが上流の処理能力を待つことがあるため、いずれの場合も最低45分間ポーリングします。長時間のストリーミング生成でタイムアウトが発生する場合は、値を増やしてください。この設定にかかわらず、タイムアウトした結果は get_sfx_task / get_generation_task（task-recovery を参照）でいつでも復旧できることも伝えてください。

安全上のルール

• 設定ファイルまたは claude mcp add を使う方法がある場合、API キー、トークン、シークレットをチャットに直接貼り付けるようユーザーに求めてはいけません。
• 設定後は、キーの値を表示したり、復唱したりしてはいけません。
• キーの作成またはローテーションにはダッシュボード（https://platform.sonilo.com/dashboard/api-keys）を、請求またはチャージには https://platform.sonilo.com/dashboard/billing を案内してください。いずれの URL の内容も捏造してはいけません。