Pro
한국어
로그인계정 Mac용 다운로드
Mac용 다운로드

문서 / API와 에이전트

Claude, Codex, MCP: 에이전트 도구

Phosphene은 로컬 서버(스튜디오) 하나이고, 브라우저 페이지, Mac 앱, 에이전트 도구가 모두 같은 HTTP API(API.md)로 이 서버와 통신해요. 그 위에 작은 도구 두 가지가 agents/에 있어요.

설명실행 방법
agents/phosphene_cli.pyphosphene 명령어: 영상, 이미지, 음성, 음악 만들기, 작업 목록 보기, 대기, 파일 가져오기, 상태 확인아무 python3(3.9 이상, 표준 라이브러리만 사용)
agents/phosphene_mcp.py같은 동작을 제공하는 MCP 서버(stdio). Claude Code, Codex 등 모든 MCP 클라이언트용위와 같음

둘 다 agents/phosphene_client.py 위에 얹은 얇은 계층이라서 스튜디오를 찾는 방식이 같고, 스튜디오가 실행 중이 아닐 때 보여 주는 메시지도 같아요.

에이전트 연결하기

Mac 앱(5.0.9 이상): Phosphene을 열고 도움말 → 에이전트 연결을 고르세요. Claude Code, Codex, 데스크톱 클라이언트 중 하나를 선택해서 명령어나 설정을 복사하세요. 앱이 Pro를 포함해 내 설치에 맞는 정확한 경로를 채워 줘요. 에이전트가 작업하는 동안에는 Phosphene을 켜 두세요. 이후 업데이트로 경로가 바뀌면 같은 메뉴에서 새 연결 정보를 복사하세요.

Pinokio: Phosphene을 시작한 다음 Pinokio가 보여 주는 스튜디오 주소 뒤에 /agents/info를 붙여 열어 보세요. 기본 설치라면 http://127.0.0.1:8198/agents/info예요. agents 섹션에 명령어와 설정이 들어 있어요. 이 주소는 Pinokio용이고, Mac 앱은 대신 도움말 메뉴를 써요.

MCP 도구: phosphene_status, phosphene_make_video, phosphene_make_image, phosphene_make_speech, phosphene_make_music, phosphene_list_jobs, phosphene_wait, phosphene_fetch, phosphene_stop. 렌더링은 몇 분 걸려요. make_* 도구는 작업을 대기열에 넣고 작업 id를 바로 돌려줘요. phosphene_wait는 최대 timeout_sec(기본 1500초) 동안 기다리며, 다시 호출할 수 있어요.

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을 붙이면 기계가 읽을 수 있는 출력이 나와요. 종료 코드: 0은 성공, 1은 스튜디오가 거부했거나 작업이 실패한 경우(그 이유 문장이 출력돼요), 2는 잘못된 인수, 3은 Phosphene이 실행 중이 아닌 경우예요. (여기서 phosphene은 python3 agents/phosphene_cli.py를 뜻해요. 원하는 대로 별칭을 만드세요.)

도구가 스튜디오를 찾는 방법

스튜디오의 포트는 실행 위치에 따라 달라요. Pinokio는 8198, 개발 프로필은 8199, Mac 앱은 8930-8999 범위의 빈 포트(PanelProcess.freePort)이고, LTX_PORT로 아무 값이나 지정할 수도 있어요. 그래서 이런 순서로 찾아요.

  1. PHOSPHENE_URL이 설정되어 있으면 그것만 써요.
  2. 모든 스튜디오는 리스너가 연결된 직후 ~/.phosphene/servers/<port>.json을 쓰고, 종료할 때 지워요(agent_discovery.py). 기록은 pid가 살아 있고 그 URL이 GET /agents/info에 "app": "phosphene"으로 응답할 때만 신뢰해요. 최신 기록부터 확인해요. PHOSPHENE_DISCOVERY_DIR로 폴더를 옮기고, PHOSPHENE_DISCOVERY=0으로 알림을 끌 수 있어요.
  3. 기록이 없으면(이전 버전 스튜디오) 8198, 8199, 그다음 8930-8999를 차례로 확인해요.

응답하는 곳이 없으면 이런 메시지가 나와요. “Phosphene is not running on this Mac. Start it first: open the Phosphene app, or press Start on Phosphene in Pinokio.” (CLI는 종료 코드 3, MCP 도구는 충돌이 아니라 도구 오류예요.)

Free, Pro, 라이선스

이 도구들은 경로를 추가하지 않고 아무것도 대신 결정하지 않아요. 모든 요청은 페이지가 직접 보내는 요청(/queue/add, /speech/generate, /upload, /status, /file)과 같아서, 스튜디오가 똑같은 검사를 적용해요. 이 Mac에서 무엇을 실행할 수 있는지, 모델 라이선스(사용자가 동의하기 전까지 HTTP 451), Free와 Pro에 무엇이 들어 있는지를 확인해요. 폼은 Pro 속도 프로필을 작업에 실어 보낼 수 없어요(make_job은 허용 목록으로 params를 만들고, test_agent_tools.py가 이를 고정해요). 모델 라이선스에 동의하는 도구는 일부러 만들지 않았어요. 누군가를 대신해 동의하는 것은 그 사람의 동의를 대신하는 일이므로, 사용자가 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": "..."}}

가볍고(디스크를 훑지 않아요) 반복해서 호출해도 안전해요. 테스트: test_agent_tools.py.

출처: docs/AGENT_TOOLS.md (공개 저장소). 공개 전에 이 웹사이트용으로 검토했어요. 영어 원문에서 번역했어요. 수정 제안하기.