ergouzi-media-mcp：自研图片/视频模型专用 MCP
安装 ergouzi-media-mcp 插件，通过自然语言生成、编辑并下载图片或视频。
这是什么
ergouzi-media-mcp 是二狗子自研图片/视频模型专用 Codex 插件型 MCP。它通过 stdio 启动本机 MCP Server，把 Ergouzi 的异步图片和视频接口提供为可调用工具：
- Codex 负责理解自然语言、选择模型和组织输入参数。
- MCP 负责读取本机媒体凭据、提交任务、查询状态、取消任务和下载结果。
- Ergouzi 媒体 API 负责实际的异步预测任务和计费。
MCP、Skill 和直接 API 的区别
| 路径 | 适合谁 | 主要配置 | 调用方式 |
|---|---|---|---|
| Media MCP | Codex 能使用更多更强的工具支持 | Codex 插件、Node.js 22+、媒体 API Key | 安装插件后用自然语言调用 |
| 图片/视频 Skill | 轻便型的调用方式 | Skill、Python 3.10+、媒体 API Key | 由 Skill 脚本提交、轮询和下载 |
| 直接 API | 开发者或需要自定义程序的用户 | HTTP 客户端、媒体 API Key | 按异步预测协议编写请求 |
MCP 与 Skill 可以同时安装，但它们是两条不通的调用路径，密钥配置并不相通。
开始前
准备以下内容：
- Codex 的 GPT/文本模型密钥：按正常方式配置给 Codex，用于对话、理解需求和编排工具。
- 独立的 MCP密钥：创建一把当前有权限调用目标图片/视频模型的密钥，只给 MCP 使用。
- Node.js 22 或更高版本：MCP Server 由 Node.js 启动。
[!IMPORTANT] 在 Codex 中使用生图或生视频需要两把密钥，MCP密钥 不是 gpt 模型密钥，不能写入 Codex 的
config.toml。
为什么 MCP密钥 必须单独配置
自研模型的接口协议，不兼容当前的openai协议
使用 Codex 自动安装配置
已经配置好 Ergouzi 中转的 Codex，可以直接复制下面的完整提示词：
请根据 https://doc.ergouzi.life/ai-guides/ergouzi-media-mcp
将 ergouzi-media-mcp 安装到 Codex ，
url: https://api.ergouzi.life，
密钥：sk-xxxx（你自己在网站创建的图片/视频分组密钥）
完成后生成一张图片示例，并告诉我图片和视频各怎么使用。
生成第一张图片
使用 ergouzi-media-mcp 生成一张雨夜上海街头图片，电影感摄影，无文字。
MCP 通常会依次调用 create_prediction、get_prediction 和 download_prediction。完成后请确认返回了任务 ID、succeeded 状态和本地文件路径。
生成第一段视频
使用 ergouzi-media-mcp 生成 5 秒、16:9 的视频：清晨云海缓慢流过山谷，电影感航拍。
模型字段、分辨率和时长限制以模型广场中该模型的 API 标签为准。
使用本地图片、视频或音频
直接提供本地文件路径，并说明输入用途：
使用 ergouzi-media-mcp 编辑 ~/input/product.png，
保持产品不变，将背景改成白色摄影棚。
使用 ergouzi-media-mcp，把 ~/input/person.png 和 ~/input/voice.mp3
生成一段 720p 口播视频。
可用工具和任务恢复
| 工具 | 用途 |
|---|---|
check_configuration | 检查本地凭据、权限和 API 连通性，不返回完整 API Key。 |
list_models | 列出当前媒体 Key 可用的模型。 |
get_model_schema | 查询模型当前的输入和输出 Schema。 |
create_prediction | 创建图片或视频异步任务并返回任务 ID。 |
get_prediction | 查询任务状态，也可以进行有上限的等待。 |
cancel_prediction | 在用户明确确认后请求取消仍在运行的任务。 |
download_prediction | 下载成功结果并写入本地回执。 |
创建计费任务和取消任务都需要用户明确确认；查询、轮询和下载不需要重复确认。
完整调用链是：check_configuration → list_models → get_model_schema → 用户确认 → create_prediction → get_prediction → download_prediction。
如果任务中断，保留 task_ 开头的任务 ID，直接告诉 Codex：
继续查询任务 task_xxx。
不要因为客户端超时就重新创建任务，否则可能重复计费。确实不需要继续时，可以明确要求 Codex 调用 cancel_prediction，然后在确认取消后执行。
常见问题
返回 401 或 403
确认配置的是独立媒体 API Key，并且密钥分组支持目标图片/视频模型。不要用 Codex 的 GPT/文本模型密钥替代媒体 Key。
模型不可用或参数错误
先调用 list_models，再使用返回列表中的模型；字段、枚举和输入文件要求以模型广场的 API 标签为准。
任务长时间没有完成
保留原任务 ID，继续调用 get_prediction，不要重复提交。余额、429、鉴权和网络错误可参考 API 错误与网络排查。