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.py | il comando phosphene: crea video / immagini / parlato / musica, elenca i lavori, aspetta, scarica i file, mostra lo stato | qualsiasi python3 (3.9+, solo libreria standard) |
agents/phosphene_mcp.py | un server MCP (stdio) con le stesse azioni, per Claude Code, Codex o qualsiasi client MCP | uguale |
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:
PHOSPHENE_URL, se impostato, viene usato e nient’altro.- Ogni studio scrive
~/.phosphene/servers/<port>.jsonnon 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 aGET /agents/infocon"app": "phosphene". Dal più recente.PHOSPHENE_DISCOVERY_DIRsposta la cartella;PHOSPHENE_DISCOVERY=0disattiva l’annuncio. - 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.