GPT Image 2.5 API 已上线，立即体验图片生成与编辑 →
PoYoPoYo
PoYo CLInpm 包已发布

每一个 PoYo 模型，都能从终端、脚本与 Agent 调用。

无需 API Key 即可查看 PoYo 实时目录中当前可用模型的输入 Schema 和公开价格；执行模型时再配置 Key。长任务即使超过 CLI 等待时间，也能用同一个 task_id 继续查询结果。

$npx -y @poyoapi/cli help
在 npm 查看GitHub打开文档

三步，从发现模型到拿到结果

无需全局安装。确认 Node.js 版本，查看模型参数，登录并完成第一次执行。

1

确认环境并运行 CLI

需要 Node.js 20 或更高版本。node --version 输出 v20 或更高版本后，即可直接通过 npx 运行，无需全局安装。

node --version
npx -y @poyoapi/cli help
2

查找并检查模型

本例固定查找当前可用的 gpt-image-2，再读取它的实时输入 Schema 和公开价格。这两条命令不需要 API Key。

npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
npx -y @poyoapi/cli describe gpt-image-2
3

登录、验证并执行

先创建 API Key，再依次完成下面三项操作。付费执行前请通过 describe 确认价格；生成失败不会扣除积分。

创建 API Key

1. 配置 API Key

预期：CLI 不回显输入的 Key，并在保存后显示 keyring 或 config。系统凭据管理器不可用时，会回退到当前用户的 PoYo 配置文件。

npx -y @poyoapi/cli auth login

2. 验证账户和余额

预期：显示账户信息和可用余额；401 表示 Key 缺失或无效。

npx -y @poyoapi/cli account

3. 确认价格后执行

这是付费请求。成功的 JSON 结果会包含 task_id、最终状态和输出文件。

npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --format json

为真实的多模态工作流而设计

实时 Catalog 告诉 CLI 当前有哪些模型、各自接受哪些输入、如何跟踪长任务，以及脚本能接收什么输出格式。

执行前先查目录

models 列出公开目录，describe 返回单个模型准确的 Schema、支持协议、执行模式、回调能力和计费信息。

这两条命令都不需要 API Key。

Schema 自动变成命令参数

CLI 读取每个模型的实时 Schema，并把其中的字段转换为该模型专用的命令行参数。

未知模型参数会在本地报错。必填字段和完整 JSON Schema 校验仍由 API 完成。

只提交一次，用 task_id 继续

submit 会立即返回 task_id。task get 读取当前状态，task wait 会持续轮询到完成或超时。

视频、音频和 3D 等长任务优先使用 submit。

为脚本与 CI 提供结构化输出

给人查看时使用 table；脚本和 CI 使用 JSON、JSONL 或 CSV。非流式命令还可以把结果写入文件。

非流式命令可使用 --output FILE；流式文本和 JSONL 始终写入 stdout。

一次真实的 PoYo CLI 会话

浏览公开目录，检查模型当前的输入与价格，再为脚本请求结构化输出。

~/projects/poyo-demo
# 1. 查找并检查模型
$ npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1

# 2. 查看实时 Schema
$ npx -y @poyoapi/cli describe gpt-image-2
  prompt          string   required
  size            string   default: "1:1"
  output_format   string   enum: jpeg | png

# 3. 登录、验证并执行
$ npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --size 4:3 --output-format png --format json
{
  "task_id": "task_7f31b2",
  "status": "succeeded",
  "files": ["https://storage.poyo.ai/.../image.png"]
}

任务生命周期

长任务无需重新开始

视频、音频、3D 等长任务只需提交一次。保存 task_id，即可从另一个终端或 CI 步骤继续等待。

CLI 超时不会取消后端任务。请继续使用同一个 task_id，不要重复提交相同任务。

不希望终端持续等待时使用 submit
$ npx -y @poyoapi/cli submit gpt-image-2 --prompt "cinematic product photo" --format json

task_id task_7f31b2

$ npx -y @poyoapi/cli task wait TASK_ID --timeout 300 --format json

status succeeded

预计 90 秒内完成时使用 run

run 每两秒查询一次任务，默认最多等待 90 秒，也可以指定其他超时时间。

不希望终端持续等待时使用 submit

复制 submit 返回的 task_id，用它替换等待命令中的 TASK_ID；之后可以从另一个终端或 CI 步骤继续查询。

为不同调用方选择正确接口

开发者和 Shell 脚本使用 CLI，Agent 工具调用使用 MCP，应用内部使用 REST；需要复用 PoYo 操作步骤和安全规则时使用 Skill。

PoYo CLI

开发者、终端与 CI

人或 Shell 脚本需要发现并运行模型、继续查询任务，并根据进程退出码执行下一步。

安装 CLI

MCP

AI Agent 与编程客户端

Agent 需要通过一个连接发现 Schema、价格和执行工具。

查看 MCP

REST API

应用和后端服务

应用需要通过 HTTP 直接控制请求、流式传输、重试和回调。

打开文档

PoYo Skill

可重复的 Agent 工作流

Agent 在使用 CLI、MCP 或 REST 之外，还需要可复用的操作步骤和安全规则。

查看 Skill

PoYo CLI 常见问题

仍然不确定该用哪条命令？ 联系 PoYo 支持→

开源，从任意终端即可开始。

CLI 采用 MIT 许可，已发布到 npm 并在 GitHub 开发。先浏览公开目录，准备执行模型时再创建 API Key。

创建 API Key在 npm 查看