ヘルプ / APIとエージェント
Claude、Codex、MCP:エージェント用ツール
Phospheneは、ひとつのローカルサーバー(スタジオ)です。ブラウザのページも、Macアプリも、エージェントツールも、同じHTTP API(API.md)を通じてスタジオと通信します。その上に、agents/にある2つの小さなツールが載っています。
| 内容 | 実行方法 | |
|---|---|---|
agents/phosphene_cli.py | phospheneコマンド。動画、画像、音声、音楽の作成、ジョブの一覧、待機、ファイルの取得、ステータスの確認ができます | 任意のpython3(3.9以降、標準ライブラリのみ) |
agents/phosphene_mcp.py | 同じ操作ができるMCPサーバー(stdio)。Claude Code、Codex、そのほかのMCPクライアント向けです | 同上 |
どちらもagents/phosphene_client.pyの上に載った薄いレイヤーなので、スタジオの見つけ方も、スタジオが動いていないときの伝え方も同じです。
エージェントを接続する
Macアプリ(5.0.9以降): Phospheneを開き、Help → Connect an agentを選びます。Claude Code、Codex、またはデスクトップクライアントを選んで、コマンドか設定をコピーしてください。アプリが、Proを含むお使いのインストールに合った正確なパスを用意します。エージェントが作業しているあいだは、Phospheneを開いたままにしてください。のちのアップデートでパスが変わった場合は、同じメニューから新しい接続をコピーし直してください。
Pinokio: Phospheneを起動し、Pinokioが表示するスタジオのアドレスで/agents/infoを開きます。標準のインストールでは、http://127.0.0.1:8198/agents/infoです。そのagentsセクションに、コマンドと設定が載っています。このアドレスはPinokio用で、MacアプリではHelpメニューを使います。
MCPツール:phosphene_status、phosphene_make_video、phosphene_make_image、phosphene_make_speech、phosphene_make_music、phosphene_list_jobs、phosphene_wait、phosphene_fetch、phosphene_stop。レンダリングには数分かかります。make_*ツールはキューに入れてジョブIDを返し、phosphene_waitはtimeout_sec(デフォルトは1500秒)まで待機して、もう一度呼び出すこともできます。
CLI
phosphene status
phosphene video "A night ferry crosses a dark harbour in light rain ..." --seconds 5 --out ./clips
phosphene video "..." --engine h3 --quality draft --seconds 10 --wait
phosphene video "..." --image still.png # image to video (the picture is uploaded first)
phosphene image "a travel poster of a red tram" --n 2 --aspect 3:4 --out ./stills
phosphene jobs ; phosphene wait JOB --out DIR ; phosphene fetch JOB --out DIR ; phosphene stop
phosphene servers # every studio answering on this Mac
どのコマンドでも--jsonを付けると、機械で読める出力になります。終了コード:0は成功、1はスタジオが拒否したかジョブが失敗した場合(その理由の文が表示されます)、2は引数の誤り、3はPhospheneが動いていない場合です。(ここでのphospheneはpython3 agents/phosphene_cli.pyのことです。お好きにエイリアスを付けてください。)
ツールがスタジオを見つける方法
スタジオのポートは、動いている場所によって決まります。Pinokioでは8198、開発プロファイルでは8199、Macアプリでは8930〜8999の空いているポート(PanelProcess.freePort)、LTX_PORTを指定すれば任意のポートです。そのため、次の順で探します。
PHOSPHENE_URLが設定されていれば、それだけを使い、ほかは見ません。- スタジオは、リスナーがバインドされるとすぐに
~/.phosphene/servers/<port>.jsonを書き出し、停止すると削除します(agent_discovery.py)。レコードが信頼されるのは、そのpidが生きていて、URLのGET /agents/infoが"app": "phosphene"を返すときだけです。新しいものが優先されます。PHOSPHENE_DISCOVERY_DIRでフォルダを移せます。PHOSPHENE_DISCOVERY=0で通知をオフにできます。 - レコードがない場合(古いスタジオ)は、8198、8199、そして8930〜8999の順に試します。
どれも応答しなければ、次のように表示されます。「Phosphene is not running on this Mac. Start it first: open the Phosphene app, or press Start on Phosphene in Pinokio.」(CLIでは終了コード3、MCPツールではクラッシュではなくツールエラーになります)。
Free、Pro、ライセンス
ツールは、ルートを追加することも、何かを判断することもありません。すべてのリクエストは、ページ自身が行うリクエスト(/queue/add、/speech/generate、/upload、/status、/file)なので、スタジオは同じチェックを適用します。このMacで動かせるもの、モデルのライセンス(本人が同意するまではHTTP 451)、FreeとProに含まれるものです。フォームからProのスピードプロファイルをジョブに持ち込むことはできません(make_jobは許可リストからparamsを組み立てます。test_agent_tools.pyがそれを固定しています)。モデルのライセンスに同意するツールは、意図的に用意していません。 他人に代わって同意することは、その人が同意したことになってしまうので、本人がPhosphene上で一度だけ行います。
GET /agents/info
{"app": "phosphene", "api": 1, "url": "http://127.0.0.1:8198", "port": 8198, "pid": 123,
"version": "5.0.0", "distribution": "pinokio" | "mac-app", "edition": "free" | "pro", "profile": "production",
"pro": {"active": false, ...}, // GET /pro/status
"engines": {"ltx": {"available": true, "qualities": [...]},
"h3": {"available": false, "qualities": [...], "lengths": ["3s", "5s", "10s", "15s", ...]},
"speech": {...}, "music": {...}, "image": {...}},
"outputs_dir": "...",
"agents": {"cli": "...", "mcp": "...", "python": "...", "mcp_config": {...}, "claude_code": "...", "codex": "..."}}
軽量(ディスクを走査しません)なので、安全にポーリングできます。テスト:test_agent_tools.py。
出典:docs/AGENT_TOOLS.md(公開リポジトリ)。公開前にこのウェブサイト向けに確認済みです。英語の原文から翻訳しています。編集を提案する。