Docs / API e agentes
Claude, Codex e MCP: ferramentas para agentes
O Phosphene é um único servidor local (o estúdio) com o qual a página do navegador, o app para Mac e as ferramentas de agente conversam pela mesma API HTTP (API.md). Duas ferramentas pequenas ficam por cima dele, em agents/:
| o que é | como executar | |
|---|---|---|
agents/phosphene_cli.py | o comando phosphene: criar vídeo / imagens / fala / música, listar jobs, esperar, buscar arquivos, status | qualquer python3 (3.9+, só biblioteca padrão) |
agents/phosphene_mcp.py | um servidor MCP (stdio) com as mesmas ações, para o Claude Code, o Codex ou qualquer cliente MCP | igual |
As duas são camadas finas sobre agents/phosphene_client.py, então encontram o estúdio do mesmo jeito e dizem a mesma coisa quando ele não está rodando.
Conectar um agente
App para Mac (5.0.9 ou posterior): abra o Phosphene e escolha Ajuda → Conectar um agente. Selecione o Claude Code, o Codex ou o seu cliente de desktop e copie o comando ou a configuração. O app fornece os caminhos exatos da sua instalação, incluindo o Pro. Mantenha o Phosphene aberto enquanto o agente trabalha. Se uma atualização posterior mudar os caminhos, copie uma nova conexão pelo mesmo menu.
Pinokio: inicie o Phosphene e abra /agents/info no endereço do Studio mostrado pelo Pinokio. Uma instalação padrão usa http://127.0.0.1:8198/agents/info. A seção agents dele fornece o comando e a configuração. Este endereço é para o Pinokio; o app para Mac usa o menu Ajuda.
Ferramentas MCP: phosphene_status, phosphene_make_video, phosphene_make_image, phosphene_make_speech,
phosphene_make_music, phosphene_list_jobs, phosphene_wait, phosphene_fetch, phosphene_stop.
As renderizações levam minutos: uma ferramenta make_* coloca na fila e devolve um id de job; phosphene_wait bloqueia por até
timeout_sec (padrão 1500 s) e pode ser chamada de novo.
A 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 em qualquer comando dá uma saída legível por máquina. Códigos de saída: 0 ok, 1 o estúdio recusou
ou o job falhou (a frase dele é impressa), 2 argumentos inválidos, 3 o Phosphene não está rodando.
(phosphene aqui é python3 agents/phosphene_cli.py; crie o alias que preferir.)
Como uma ferramenta encontra o estúdio
A porta do estúdio depende de onde ele roda: 8198 no Pinokio, 8199 no perfil de desenvolvimento, uma porta livre em 8930-8999 no app para Mac (PanelProcess.freePort), qualquer uma com LTX_PORT. Então:
PHOSPHENE_URL, quando definido, é usado e nada mais.- Cada estúdio escreve
~/.phosphene/servers/<port>.jsonassim que o listener dele está ligado e o remove ao parar (agent_discovery.py). Um registro só é confiável se o pid dele está vivo e a URL responde aGET /agents/infocom"app": "phosphene". O mais recente primeiro.PHOSPHENE_DISCOVERY_DIRmuda a pasta;PHOSPHENE_DISCOVERY=0desliga o anúncio. - Sem nenhum registro (um estúdio mais antigo): 8198, 8199 e depois 8930-8999.
Nada respondendo: “Phosphene is not running on this Mac. Start it first: open the Phosphene app, or press Start on Phosphene in Pinokio.” (saída 3 da CLI; um erro de ferramenta no MCP, nunca uma falha).
Free, Pro e licenças
As ferramentas não adicionam nenhuma rota e não decidem nada. Cada requisição é uma que a própria página faz
(/queue/add, /speech/generate, /upload, /status, /file), então o estúdio aplica as mesmas verificações:
o que este Mac consegue rodar, as licenças dos modelos (HTTP 451 até a pessoa aceitar) e o que o Free e o Pro
incluem. Um formulário não consegue levar um perfil de velocidade Pro para dentro de um job (make_job monta o params a partir de uma
lista de permitidos; test_agent_tools.py garante isso). De propósito, não existe nenhuma ferramenta que aceite a licença de um modelo: aceitar em nome de alguém é aceitar por essa pessoa, então ela faz isso uma vez, no
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": "..."}}
Barato (sem percorrer o disco) e seguro para consultar repetidamente. Testes: test_agent_tools.py.
Fonte: docs/AGENT_TOOLS.md no repositório público. Revisado para este site antes da publicação. Traduzido do original em inglês. Sugerir uma edição.