Pro
IT
AccediAccount Scarica per Mac
Scarica per Mac

Docs / API e agenti

Claude, Codex e MCP: strumenti per agenti

Phosphene è un unico server locale (lo studio) con cui la pagina del browser, l’app per Mac e gli strumenti degli agenti parlano tutti attraverso la stessa API HTTP (API.md). Sopra di esso stanno due piccoli strumenti, in agents/:

cos’ècome eseguirlo
agents/phosphene_cli.pyil comando phosphene: crea video / immagini / parlato / musica, elenca i lavori, aspetta, scarica i file, mostra lo statoqualsiasi python3 (3.9+, solo libreria standard)
agents/phosphene_mcp.pyun server MCP (stdio) con le stesse azioni, per Claude Code, Codex o qualsiasi client MCPuguale

Entrambi sono strati sottili sopra agents/phosphene_client.py, quindi trovano lo studio nello stesso modo e dicono la stessa cosa quando non è in esecuzione.

Collegare un agente

App per Mac (5.0.9 o successiva): apri Phosphene, poi scegli Aiuto → Collega un agente. Seleziona Claude Code, Codex o il tuo client desktop e copia il comando o la configurazione. L’app fornisce i percorsi esatti per la tua installazione, Pro compreso. Tieni Phosphene aperto mentre l’agente lavora. Se un aggiornamento successivo cambia i percorsi, copia una nuova connessione dallo stesso menu.

Pinokio: avvia Phosphene, poi apri /agents/info all’indirizzo dello Studio mostrato da Pinokio. Un’installazione predefinita usa http://127.0.0.1:8198/agents/info. La sua sezione agents fornisce il comando e la configurazione. Questo indirizzo è per Pinokio; l’app per Mac usa invece il suo menu Aiuto.

Strumenti MCP: phosphene_status, phosphene_make_video, phosphene_make_image, phosphene_make_speech, phosphene_make_music, phosphene_list_jobs, phosphene_wait, phosphene_fetch, phosphene_stop. I render richiedono minuti: uno strumento make_* mette in coda e restituisce un id del lavoro; phosphene_wait resta in attesa fino a timeout_sec (predefinito 1500 s) e può essere richiamato di nuovo.

La 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 su qualsiasi comando dà un output leggibile da una macchina. Codici di uscita: 0 ok, 1 lo studio ha rifiutato o il lavoro è fallito (la sua frase viene stampata), 2 argomenti errati, 3 Phosphene non è in esecuzione. (phosphene qui è python3 agents/phosphene_cli.py; dagli l’alias che preferisci.)

Come uno strumento trova lo studio

La porta dello studio dipende da dove gira: 8198 in Pinokio, 8199 per il profilo di sviluppo, una porta libera tra 8930-8999 nell’app per Mac (PanelProcess.freePort), qualsiasi valore con LTX_PORT. Quindi:

  1. PHOSPHENE_URL, se impostato, viene usato e nient’altro.
  2. Ogni studio scrive ~/.phosphene/servers/<port>.json non appena il suo listener è attivo e lo rimuove quando si ferma (agent_discovery.py). Un record è considerato attendibile solo se il suo pid è vivo e l’URL risponde a GET /agents/info con "app": "phosphene". Dal più recente. PHOSPHENE_DISCOVERY_DIR sposta la cartella; PHOSPHENE_DISCOVERY=0 disattiva l’annuncio.
  3. Senza record (uno studio più vecchio): 8198, 8199, poi 8930-8999.

Se nessuno risponde: “Phosphene is not running on this Mac. Start it first: open the Phosphene app, or press Start on Phosphene in Pinokio.” (CLI con uscita 3; per MCP un errore dello strumento, mai un crash).

Free, Pro e licenze

Gli strumenti non aggiungono alcuna route e non decidono nulla. Ogni richiesta è una richiesta che fa la pagina stessa (/queue/add, /speech/generate, /upload, /status, /file), quindi lo studio applica gli stessi controlli: cosa può eseguire questo Mac, le licenze dei modelli (HTTP 451 finché la persona non le accetta), e cosa includono Free e Pro. Un modulo non può trasportare un profilo di velocità Pro dentro un lavoro (make_job costruisce params da una lista di valori consentiti; test_agent_tools.py lo fissa). Volutamente non esiste uno strumento che accetti la licenza di un modello: accettare per conto di qualcuno è accettare al suo posto, quindi è la persona a farlo una volta in 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": "..."}}

Leggero (nessuna scansione del disco), sicuro da interrogare di continuo. Test: test_agent_tools.py.

Fonte: docs/AGENT_TOOLS.md nel repository pubblico. Rivisto per questo sito prima della pubblicazione. Tradotto dall'originale inglese. Suggerisci una modifica.