Docs / API et agents
Claude, Codex et MCP : outils pour agents
Phosphene est un seul serveur local (le studio) avec lequel la page du navigateur, l’app Mac et les outils d’agent
dialoguent tous par la même API HTTP (API.md). Deux petits outils s’appuient dessus, dans agents/ :
| ce que c’est | à lancer avec | |
|---|---|---|
agents/phosphene_cli.py | la commande phosphene : créer vidéo / images / voix / musique, lister les tâches, attendre, récupérer les fichiers, état | n’importe quel python3 (3.9+, bibliothèque standard uniquement) |
agents/phosphene_mcp.py | un serveur MCP (stdio) avec les mêmes actions, pour Claude Code, Codex ou tout client MCP | idem |
Les deux sont de fines couches au-dessus de agents/phosphene_client.py : ils trouvent donc le studio de la même
façon et disent la même chose quand il ne tourne pas.
Connecter un agent
App Mac (5.0.9 ou plus récent) : ouvrez Phosphene, puis choisissez Aide → Connecter un agent. Sélectionnez Claude Code, Codex ou votre client de bureau et copiez la commande ou la configuration. L’app fournit les chemins exacts pour votre installation, y compris Pro. Gardez Phosphene ouvert pendant que l’agent travaille. Si une mise à jour ultérieure change les chemins, copiez une nouvelle connexion depuis le même menu.
Pinokio : démarrez Phosphene, puis ouvrez /agents/info à l’adresse du Studio indiquée par Pinokio. Une installation par défaut utilise http://127.0.0.1:8198/agents/info. Sa section agents fournit la commande et la configuration. Cette adresse est pour Pinokio ; l’app Mac utilise plutôt son menu Aide.
Outils MCP : phosphene_status, phosphene_make_video, phosphene_make_image, phosphene_make_speech,
phosphene_make_music, phosphene_list_jobs, phosphene_wait, phosphene_fetch, phosphene_stop.
Les rendus prennent des minutes : un outil make_* met en file et renvoie un identifiant de tâche ; phosphene_wait bloque jusqu’à
timeout_sec (1500 s par défaut) et peut être rappelé.
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 sur n’importe quelle commande donne une sortie lisible par une machine. Codes de sortie : 0 ok, 1 le studio a refusé
ou la tâche a échoué (sa phrase est affichée), 2 arguments invalides, 3 Phosphene ne tourne pas.
(phosphene correspond ici à python3 agents/phosphene_cli.py ; donnez-lui l’alias que vous voulez.)
Comment un outil trouve le studio
Le port du studio dépend de l’endroit où il tourne : 8198 dans Pinokio, 8199 pour le profil de développement, un port libre
entre 8930 et 8999 dans l’app Mac (PanelProcess.freePort), n’importe lequel avec LTX_PORT. Donc :
PHOSPHENE_URL, quand il est défini, est utilisé et rien d’autre.- Chaque studio écrit
~/.phosphene/servers/<port>.jsonune fois son écouteur lié et le supprime quand il s’arrête (agent_discovery.py). Un enregistrement n’est cru que si son pid est vivant et si l’URL répond àGET /agents/infoavec"app": "phosphene". Le plus récent d’abord.PHOSPHENE_DISCOVERY_DIRdéplace le dossier ;PHOSPHENE_DISCOVERY=0désactive l’annonce. - Sans enregistrement (un studio plus ancien) : 8198, 8199, puis 8930 à 8999.
Si rien ne répond : “Phosphene is not running on this Mac. Start it first: open the Phosphene app, or press Start on Phosphene in Pinokio.” (sortie CLI 3 ; une erreur d’outil MCP, jamais un plantage).
Gratuit, Pro et licences
Les outils n’ajoutent aucune route et ne décident de rien. Chaque requête est une requête que la page elle-même fait
(/queue/add, /speech/generate, /upload, /status, /file), donc le studio applique les mêmes contrôles :
ce que ce Mac peut faire tourner, les licences des modèles (HTTP 451 tant que la personne n’a pas accepté), et ce que les versions gratuite et Pro
incluent. Un formulaire ne peut pas faire passer un profil de vitesse Pro dans une tâche (make_job construit params à partir d’une
liste autorisée ; test_agent_tools.py le garantit). Il n’existe volontairement aucun outil qui accepte une licence de
modèle : accepter au nom de quelqu’un, c’est accepter à sa place, donc la personne le fait une fois dans
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": "..."}}
Peu coûteux (aucun parcours de disque), sans risque à interroger régulièrement. Tests : test_agent_tools.py.
Source : docs/AGENT_TOOLS.md dans le dépôt public. Relu pour ce site avant publication. Traduit de l'original anglais. Suggérer une modification.