PoYo Video & Image Tools for Codex

一组零 npm 依赖的本地 MCP Server，让 Codex 可以调用 PoYo seedance-2-fast 生成视频，也可以调用 gpt-image-2 / gpt-image-2-edit 生成和编辑图片。

功能

• 文生视频、首尾帧生视频，以及图片/视频/音频参考生成
• 支持 480p、720p，时长 4–15 秒
• 自动轮询任务并在结果 URL 过期前下载 MP4
• 同时支持一键生成和异步提交/查询/下载
• 使用 GPT Image 2 文生图、参考图引导生成，以及多图编辑
• 支持 low/medium/high、1K/2K/4K、预设比例与自定义尺寸
• 自动下载生成图片到本地，避免结果 URL 过期

环境要求

• Codex CLI
• Node.js 18 或更高版本（可用 node --version 检查）
• PoYo API Key

让电脑里的 Codex Agent 安装

最简单的方法是把下面这句话直接发给电脑里的 Codex Agent：

请在终端执行以下操作：克隆 https://github.com/NovvyAI/poyo_videogen_mcp_tool.git，进入仓库，复制 .env_poyo.example 为 .env_poyo，提醒我填入 POYO_API_KEY，然后执行 codex mcp add poyo-image -- node "$(pwd)/image-server.mjs"。完成后运行 codex mcp list 验证 poyo-image 已安装，并提醒我新建一个 Codex 会话。

Agent 可以完成代码下载和 MCP 注册，但出于安全考虑，客户应自行把 PoYo API Key 填入 .env_poyo，不要把 Key 发送到聊天或提交到 GitHub。

如果只需要新的图片工具，安装 poyo-image 即可，不需要安装视频工具。完整的手动步骤如下。

手动安装到 Codex

1. 下载代码

git clone https://github.com/NovvyAI/poyo_videogen_mcp_tool.git poyo-video-tool
cd poyo-video-tool

2. 配置 API Key

复制示例配置文件：

cp .env_poyo.example .env_poyo

然后编辑 .env_poyo，填入自己的 API Key：

POYO_API_KEY="替换成你的-api-key"

.env_poyo 已加入 .gitignore，不要提交 API Key。也可以通过进程环境变量提供 POYO_API_KEY；环境变量优先于文件配置。

可选配置：

# 使用兼容的自定义 API 地址
POYO_BASE_URL="https://api.poyo.ai"

如需把凭据文件放到其他位置，可以设置 POYO_ENV_FILE=/absolute/path/to/.env_poyo。

3. 注册新的图片 MCP

只安装图片工具：

codex mcp add poyo-image -- node "$(pwd)/image-server.mjs"

如果还需要原有的视频工具，再执行：

codex mcp add poyo-video -- node "$(pwd)/server.mjs"

确认图片 MCP 已安装：

codex mcp list

输出中应出现 poyo-image。然后重新启动 Codex，或新建一个 Codex 会话；已经打开的会话通常不会自动加载刚安装的 MCP。

可以在新会话中这样验证：

请列出 poyo-image 提供的工具。如果可以看到 poyo_generate_image 和 poyo_edit_image，告诉我安装成功，不要实际生成图片。

需要卸载时执行：

codex mcp remove poyo-video
codex mcp remove poyo-image

如果移动或删除了仓库目录，请先卸载，再从新目录重新执行安装命令。

更新到最新版

进入之前克隆的仓库执行：

git pull

如果 image-server.mjs 的路径没有改变，通常不需要重新注册 MCP；新建一个 Codex 会话即可加载最新版。

作为 Codex Plugin 分发

仓库已包含 .codex-plugin/plugin.json 和 .mcp.json，可以直接作为 Codex plugin 放入团队 marketplace。团队管理员将该目录加入 marketplace 后，同事可执行：

codex plugin add poyo-video-tool@<TEAM_MARKETPLACE_NAME>

Plugin 安装完成后，仍需在插件目录放置 .env_poyo，或让启动 Codex 的环境提供 POYO_API_KEY。请在新会话中使用新安装的工具。

在 Codex 中使用

安装后可以直接对 Codex 说：

使用 poyo_generate_video 生成一个 5 秒、720p、16:9 的电影感日落海滩视频，并保存到 generated_videos/sunset.mp4。

使用参考素材时，素材必须是公网可直接下载的 HTTP(S) URL。例如：

使用这张图片作为首帧生成 8 秒 9:16 视频：https://example.com/start.jpg。

生成图片：

使用 poyo_generate_image 生成一张 high、2K、16:9 的电影感未来城市图片，并保存到 generated_images/city.png。

编辑图片（参考图必须是公网可直接下载的 HTTP(S) URL）：

使用 poyo_edit_image 把 https://example.com/product.jpg 的背景改成白色摄影棚，并保存到 generated_images/product-edited.png。

MCP Tools

• poyo_generate_video：提交、等待并下载视频，推荐日常使用。
• poyo_start_generation：只提交任务，立即返回 task_id。
• poyo_get_status：用 task_id 查询任务状态。
• poyo_wait_and_download：继续等待已有任务，并在完成后下载视频。

默认输出到 Codex 当前工作目录下的 generated_videos/。也可以通过 output_path 指定绝对路径或相对路径。

Image Tools

• poyo_generate_image：使用 gpt-image-2 生成、等待并下载单张图片。
• poyo_edit_image：使用 gpt-image-2-edit 编辑一张或多张参考图片并下载结果。
• poyo_image_start_generation：异步提交生成或编辑任务；编辑时设置 edit: true。
• poyo_image_get_status：查询图片任务状态。
• poyo_image_wait_and_download：等待已有任务并下载结果。

图片默认输出到 Codex 当前工作目录下的 generated_images/。

图片参数：

• quality：low、medium、high，默认 low
• resolution：1K、2K、4K，默认 1K
• size：auto、1:1、2:3、3:2、4:3、3:4、4:5、5:4、16:9、9:16、21:9，或 WIDTHxHEIGHT
• 自定义尺寸要求 2K/4K、宽高均为 16 的倍数、最长边不超过 3840、比例不超过 3:1、总像素为 655,360–8,294,400
• image_urls：公网参考图 URL；poyo_edit_image 至少需要一张
• 每次请求生成一张图片

参数限制

• aspect_ratio：auto、21:9、16:9、4:3、1:1、3:4、9:16
• resolution：480p 或 720p
• duration_seconds：4–15 的整数
• image_urls：最多 2 个，用于首帧和可选尾帧
• reference_image_urls：最多 9 个
• reference_video_urls：最多 3 个
• reference_audio_urls：最多 3 个，且必须同时提供参考图片或视频
• image_urls 不能与 reference_*_urls 混用；参考素材总数最多 12 个

PoYo 返回的下载 URL 会过期，因此建议优先使用 poyo_generate_video 或在任务完成后立即调用 poyo_wait_and_download。

故障排查

• POYO_API_KEY is not set：确认 .env_poyo 与 image-server.mjs / server.mjs 位于同一目录，并重启 Codex。
• Codex 找不到图片工具：运行 codex mcp list，确认 poyo-image 已注册；然后新建会话。
• 素材 URL 报错：确认它是公网可访问、无需登录、可直接下载的 HTTP(S) 地址。
• 本地等待超时：生成任务仍可能在服务端运行，使用返回的 task_id 调用 poyo_wait_and_download 继续等待。