Pro
日本語
サインインアカウント Mac版をダウンロード
Mac版をダウンロード

ヘルプ / APIとエージェント

Claude、Codex、MCP:エージェント用ツール

Phospheneは、ひとつのローカルサーバー(スタジオ)です。ブラウザのページも、Macアプリも、エージェントツールも、同じHTTP API(API.md)を通じてスタジオと通信します。その上に、agents/にある2つの小さなツールが載っています。

内容実行方法
agents/phosphene_cli.pyphospheneコマンド。動画、画像、音声、音楽の作成、ジョブの一覧、待機、ファイルの取得、ステータスの確認ができます任意の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を指定すれば任意のポートです。そのため、次の順で探します。

  1. PHOSPHENE_URLが設定されていれば、それだけを使い、ほかは見ません。
  2. スタジオは、リスナーがバインドされるとすぐに~/.phosphene/servers/<port>.jsonを書き出し、停止すると削除します(agent_discovery.py)。レコードが信頼されるのは、そのpidが生きていて、URLのGET /agents/infoが"app": "phosphene"を返すときだけです。新しいものが優先されます。PHOSPHENE_DISCOVERY_DIRでフォルダを移せます。PHOSPHENE_DISCOVERY=0で通知をオフにできます。
  3. レコードがない場合(古いスタジオ)は、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(公開リポジトリ)。公開前にこのウェブサイト向けに確認済みです。英語の原文から翻訳しています。編集を提案する。