GPT Image 2.5 API が登場。画像生成・編集を今すぐ体験 →
PoYoPoYo
PoYo CLInpm パッケージ公開中

PoYo モデルを検索して実行 すべてターミナルから。

API Key なしで最新のモデルカタログと Schema を確認できます。チャット、生成、task_id によるタスク再開が必要になった時点で認証してください。

$npx -y @poyoapi/cli help
npm で見るGitHubDocs を開く

3 ステップで PoYo CLI を使い始める

まず CLI を実行し、models と describe でモデルを選びます。モデルの実行またはアカウント情報の取得時だけ API Key が必要です。

1

CLI を起動

グローバルインストールは不要です。公開パッケージには Node.js 20 以上が必要です。

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 を作成し、以下の 3 つのコマンドを順番に実行します。有料実行の前に 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

モデル Schema から CLI 引数を生成する

chat、run、submit の前に CLI が選択したモデルの Schema を読み、各項目をモデル専用の引数に変換します。

実行前にモデルを確認

models は公開カタログを一覧表示し、describe は Schema、プロトコル、実行方式、Callback、課金情報を返します。

この 2 つは API Key なしで使えます。

生成プロンプト

Schema の文字列フィールドを通常のコマンドライン値として渡せます。

不明なモデルオプションはローカルでエラーになります。完全な JSON Schema 検証は API 側で行われます。

今は戻り、あとで再開

submit は task_id をすぐ返します。task get は状態を読み、task wait は待機を続けます。

動画、音声、3D など時間のかかる処理に適しています。

CLI の出力方法を制御する

ストリーミング chat はテキストまたは JSONL を stdout に出力します。非ストリーミングコマンドは table、JSON、JSONL、CSV を返し、ファイルにも書き込めます。

CLI は REST API と同じ endpoint と課金ルールを使用します。

タスクに合うコマンドを選ぶ

モデル検索、チャット、生成、タスク再開、ローカル MCP ブリッジは、それぞれ専用コマンドで実行します。

~/projects/poyo-demo
# 1. モデルを選択
$ npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1

# 2. 生成されたコマンド入力
$ 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"]
}

タスクの流れ

task_id で長時間タスクを再開する

PoYo は既存の公開タスク状態をそのまま返します。CLI がタイムアウトまたは終了しても、再送信せず同じタスクを照会できます。

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

短い待機には run

run は 2 秒ごとに確認し、既定では最大 90 秒待機します。

長い処理には submit

task_id を保存し、別のターミナルや CI ステップから task get または task wait を使います。

CLI、MCP、REST、Skill を選ぶ

ターミナルと CI では CLI、Agent のツール呼び出しでは MCP、アプリでは REST API、反復可能な Agent ワークフローでは Skill を使用します。

PoYo CLI

開発者、ターミナル、CI

人やスクリプトが検索、実行、再開、終了コードを必要とする場合。

CLI を導入

MCP

AI Agent とコーディングクライアント

Agent が 1 つの接続から Schema、価格、ツールを発見する場合。

MCP を見る

REST API

アプリケーションとサービス

製品側でオーケストレーション、ストリーミング、再試行、トラフィックを制御する場合。

Docs を開く

PoYo Skill

再現可能な Agent ワークフロー

Agent にインターフェースだけでなく手順と安全ルールも必要な場合。

Skill を見る

PoYo CLI FAQ

コマンドについてまだ不明ですか？ PoYo サポートに連絡→

ターミナルから最初の PoYo モデルを実行

まず公開カタログを確認し、モデルを実行する準備ができたら API Key を作成してください。

API Key を作成npm で見る