Pro
ES
Iniciar sesiónCuenta Descargar para Mac
Descargar para Mac

Ayuda / API y agentes

Claude, Codex y MCP: herramientas para agentes

Phosphene es un único servidor local (el estudio) con el que hablan, por la misma API HTTP (API.md), la página del navegador, la app para Mac y las herramientas de agentes. Encima hay dos herramientas pequeñas, en agents/:

qué escómo se ejecuta
agents/phosphene_cli.pyel comando phosphene: crea video, imágenes, voz y música, lista trabajos, espera, recupera archivos y consulta el estadocualquier python3 (3.9+, solo biblioteca estándar)
agents/phosphene_mcp.pyun servidor MCP (stdio) con las mismas acciones, para Claude Code, Codex o cualquier cliente MCPigual

Ambas son capas finas sobre agents/phosphene_client.py, así que encuentran el estudio de la misma forma y dicen lo mismo cuando no está en marcha.

Conectar un agente

App para Mac (5.0.9 o posterior): abre Phosphene y elige Ayuda → Conectar un agente. Selecciona Claude Code, Codex o tu cliente de escritorio y copia el comando o la configuración. La app te da las rutas exactas de tu instalación, incluida Pro. Mantén Phosphene abierto mientras el agente trabaja. Si una actualización posterior cambia las rutas, copia una conexión nueva desde el mismo menú.

Pinokio: inicia Phosphene y abre /agents/info en la dirección del Studio que muestra Pinokio. Una instalación por defecto usa http://127.0.0.1:8198/agents/info. Su sección agents te da el comando y la configuración. Esta dirección es para Pinokio; la app para Mac usa en su lugar su menú Ayuda.

Herramientas MCP: phosphene_status, phosphene_make_video, phosphene_make_image, phosphene_make_speech, phosphene_make_music, phosphene_list_jobs, phosphene_wait, phosphene_fetch, phosphene_stop. Los renders tardan minutos: una herramienta make_* pone el trabajo en cola y devuelve un id de trabajo; phosphene_wait espera hasta timeout_sec (por defecto 1500 s) y se puede volver a llamar.

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 en cualquier comando da una salida legible por máquinas. Códigos de salida: 0 correcto, 1 el estudio lo rechazó o el trabajo falló (se imprime su frase), 2 argumentos incorrectos, 3 Phosphene no está en marcha. (Aquí phosphene es python3 agents/phosphene_cli.py; ponle el alias que quieras.)

Cómo encuentra una herramienta el estudio

El puerto del estudio depende de dónde se ejecuta: 8198 en Pinokio, 8199 para el perfil de desarrollo, un puerto libre en 8930-8999 en la app para Mac (PanelProcess.freePort), y el que indique LTX_PORT. Entonces:

  1. Si está definida, se usa PHOSPHENE_URL y nada más.
  2. Cada estudio escribe ~/.phosphene/servers/<port>.json cuando su listener ya está enlazado y lo borra al detenerse (agent_discovery.py). Un registro solo se acepta si su pid está vivo y la URL responde a GET /agents/info con "app": "phosphene". Primero el más reciente. PHOSPHENE_DISCOVERY_DIR cambia la carpeta; PHOSPHENE_DISCOVERY=0 desactiva el anuncio.
  3. Sin ningún registro (un estudio más antiguo): 8198, 8199 y luego 8930-8999.

Si no responde nadie: “Phosphene is not running on this Mac. Start it first: open the Phosphene app, or press Start on Phosphene in Pinokio.” (salida 3 de la CLI; un error de herramienta MCP, nunca una caída).

Free, Pro y licencias

Las herramientas no añaden ninguna ruta ni deciden nada. Cada solicitud es una que la propia página también hace (/queue/add, /speech/generate, /upload, /status, /file), así que el estudio aplica las mismas comprobaciones: qué puede ejecutar este Mac, las licencias de los modelos (HTTP 451 hasta que la persona las acepta) y qué incluyen Free y Pro. Un formulario no puede meter un perfil de velocidad Pro en un trabajo (make_job construye params a partir de una lista de permitidos; test_agent_tools.py lo fija). Deliberadamente no hay ninguna herramienta que acepte la licencia de un modelo: aceptar en nombre de alguien es aceptar por esa persona, así que lo hace ella, una sola vez, en 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": "..."}}

Es barato (no recorre el disco) y se puede consultar sin riesgo. Pruebas: test_agent_tools.py.

Fuente: docs/AGENT_TOOLS.md en el repositorio público. Revisado para este sitio web antes de publicarse. Traducido del original en inglés. Sugerir un cambio.