Pro
FR
Se connecterCompte Télécharger pour Mac
Télécharger pour Mac

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.pyla commande phosphene : créer vidéo / images / voix / musique, lister les tâches, attendre, récupérer les fichiers, étatn’importe quel python3 (3.9+, bibliothèque standard uniquement)
agents/phosphene_mcp.pyun serveur MCP (stdio) avec les mêmes actions, pour Claude Code, Codex ou tout client MCPidem

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 :

  1. PHOSPHENE_URL, quand il est défini, est utilisé et rien d’autre.
  2. Chaque studio écrit ~/.phosphene/servers/<port>.json une 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/info avec "app": "phosphene". Le plus récent d’abord. PHOSPHENE_DISCOVERY_DIR déplace le dossier ; PHOSPHENE_DISCOVERY=0 désactive l’annonce.
  3. 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.