Pro
PT
EntrarConta Baixar para Mac
Baixar para Mac

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.pyo comando phosphene: criar vídeo / imagens / fala / música, listar jobs, esperar, buscar arquivos, statusqualquer python3 (3.9+, só biblioteca padrão)
agents/phosphene_mcp.pyum servidor MCP (stdio) com as mesmas ações, para o Claude Code, o Codex ou qualquer cliente MCPigual

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:

  1. PHOSPHENE_URL, quando definido, é usado e nada mais.
  2. Cada estúdio escreve ~/.phosphene/servers/<port>.json assim 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 a GET /agents/info com "app": "phosphene". O mais recente primeiro. PHOSPHENE_DISCOVERY_DIR muda a pasta; PHOSPHENE_DISCOVERY=0 desliga o anúncio.
  3. 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.