Pro
RU
ВойтиАккаунт Скачать для Mac
Скачать для Mac

Справка / API и агенты

Claude, Codex и MCP: инструменты для агентов

Phosphene работает как один локальный сервер (студия), с которым страница в браузере, приложение для Mac и агентские инструменты общаются по одному и тому же HTTP API (API.md). Поверх него в папке agents/ лежат два небольших инструмента:

что эточем запускать
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, затем откройте /agents/info по адресу студии, который показывает Pinokio. В установке по умолчанию это 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_* ставит задачу в очередь и возвращает идентификатор задачи; 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; назовите псевдоним как хотите.)

Как инструмент находит студию

Порт студии зависит от того, где она запущена: 8198 в Pinokio, 8199 для профиля разработки, свободный порт в диапазоне 8930-8999 в приложении для Mac (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 не запущен на этом Mac. Сначала запустите его: откройте приложение Phosphene или нажмите Start у Phosphene в 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 в открытом репозитории. Проверено для этого сайта перед публикацией. Переведено с английского оригинала. Предложить правку.