pollo-generate

pollo-generate

pollo-cli は認証、トークンの更新、リクエストの整形をすでに担っています。ここからのあなたの作業は、適切なモデルを選び、その入力フィールドを確認し、有効な input を作成して送信し、結果を返すことです。以下はすべてその順序、つまりモデル、入力、送信、結果に沿っています。サーバーも同じ順序で検証するため、手順を飛ばすと、その次の段階でサーバーエラーになるだけです。

セットアップ（セッションごとに一度）

1. pollo が $PATH にない場合は、リリース済みのバイナリをインストールします。ソースからビルドしないでください。

   npm i -g @pollo-ai/cli
   

   Node を使わない場合（macOS / Linux のみ）は、スタンドアロンインストーラーを使用します。

   curl -fsSL https://raw.githubusercontent.com/polloaiofficial/cli/main/install.sh | sh
   

2. pollo account status を実行します。availableCredits の数値が表示されれば、本番環境（pollo.ai、プロファイル default）にすでにログインしています。トークンがない、または期限切れというエラーが表示された場合は、次のようにします。

   pollo auth login   # opens the browser, logs into pollo.ai -> profile "default"
   

   CLI は独自の認証情報ストレージを使用し、リクエストごとに有効期間の短いトークンを更新するため、セッション中に再ログインする必要はありません。保存された認証情報を読み取ったり、表示したり、コピーしたりしないでください。以下の各コマンドはそれぞれ独立して認証を行います。
3. ユーザーから別のプロファイルを指定されない限り、default プロファイルを使用します。プロファイルを使うと、1 台のマシンで複数のログイン情報を保持できます。pollo profile list で一覧を確認でき（現在のプロファイルには * が付きます）、pollo profile use <name> で切り替えられます。また、pollo --profile <name> <command> を使うと、単一のコマンドに限ってプロファイルを変更できます。

ステップ 1 — モデルを見つけ、実際に受け付ける内容を確認する

brand／alias やフィールド名を推測しないでください。モデルのリリースに伴って変更されるため、推測しても、今ここで検索する手間を省けるどころか、次の手順でサーバーの検証エラーになるだけです。

pollo model list                        # every standard model, capabilities aggregated
pollo model list --type text2video      # only models with that capability
pollo model get <brand>/<alias> --fields   # this model's input shape

各モデルは一度だけ表示され、capabilities[] 配列を持ちます。capability は入力モード（text2video | image2video | ref2video | text2image | image2image）で、それぞれ独自の path（出力エンドポイントである /video または /image）と fields／constraints を持っています。そのため、テキストと画像の両方を受け付けるモデルは、1つの path を共有する複数の capability を持ち、kling-v3-omni のような2種類の出力に対応するモデルは、両方の path にまたがる capability を持ちます。

model list／get の --type はcapability（上記の値）でフィルタリングします。generate create／cost の --type と混同しないでください。こちらは出力エンドポイント（video|image）です。ステップ 3 を参照してください。

model get --fields（--json と同じ出力）は、エンドポイントごとに1つのエントリーを返し、それぞれ以下の形式にフラット化されています。

• fields[] — {name, type, description, values?, min?, max?}。values は列挙型の選択肢、min／max は数値フィールドの範囲です。
• constraints[] — {id, message, expr}。最終的な input に適用されるブール値のルールです（たとえば、特定のモードでのみ有効なフィールド）。作成予定の input がルールに違反する場合は、送信後に 400 エラーで判明するのではなく、送信前に message で変更すべき内容を確認できます。

入力モードは capability ですが、独立したエンドポイントではありません。リクエスト時には、input にどのフィールドを含めるかによって決まります。prompt のみならテキスト駆動、image なら画像駆動、refs なら参照画像駆動です。したがって、「このモデルは参照画像に対応していますか？」という問いは、「fields に refs を含む ref2video capability がありますか？」という意味です。推測せずに確認してください。モデルが /video と /image の両方の path を公開している場合は、ユーザーの意図に合う方を選び、その capability の fields のみを使って input を構成してください。

ユーザーが特定のモデルを指定していない場合は、まず references/model-routing.md を読んでください。ここでは、ユーザーの実際の要望を具体的な brand/alias に対応付けます（画面上のテキスト／単一画像／複数の参照画像／デフォルト別の動画分岐、品質レベル、画像ルーティング表）。また、生成結果に満足できない場合に使うフォールバックチェーンも記載されています。ブランドは推測できません（HappyHorse と Wan は alibaba/、Sora は openai/、Grok は xai/、Seedream は bytedance/）。記憶に頼らず、このファイルに従ってルーティングし、確定前に model list で確認してください。

使用する動画モデルが決まったら、ベンダー独自の方式に従って prompt フィールドの文面を作成してください。詳細は references/prompt-engineering.md を参照してください。 Kling、Veo、Seedance、Sora、Vidu、Wan、Pixverse は、それぞれ異なるプロンプト構成で最良の結果が得られます。Seedance 向けの構成を Veo に使う（またはその逆）と、期待した成果が得られない傾向があります。

ステップ 2 — 入力を準備する

画像／動画フィールド（一般的には image、images、refs）には、ローカルファイルパスまたは HTTPS URL を指定できます。自分でアップロードする必要はありません。ローカルパスを渡すと、CLI が生成処理の一環として Pollo ストレージにアップロードし、送信前にその結果の URL に置き換えます。ホストされた HTTPS URL を渡すと、そのまま使用されます（base64 は受け付けられません）。独立したアップロードコマンドはありません。アップロードは generate create／cost の処理内でのみ行われます。

Step 3 — 送信して結果を読み取る

# optional: estimate before an expensive run, or whenever the user is cost-sensitive
pollo generate cost <brand>/<alias> [--type video|image] --name value ...
# -> cost / singleCost / discountCost / discountSingleCost (+ their *Usd counterparts)

pollo generate create <brand>/<alias> [--type video|image] \
  --name value ... --json    # -> { "taskId": "...", "status": "waiting" }

pollo generate wait <taskId> [--timeout 10m] [--interval 3s] --json
# -> { "taskId", "credit", "generations": [{ "status": "succeed|failed",
#      "url", "mediaType", "failMsg" }] }

上記のフラグに関する注意事項：

• 通常、--type は不要です。CLI が /v1/models からエンドポイントを自動で解決します。モデルが両方の出力タイプに対応している場合（CLI はエラーを返してその旨を通知します）、またはすでに把握していて追加の検索を省きたい場合にのみ、--type video|image を渡してください。
• それ以外の --name value はすべて input.<name> になります。値の型は自動判定されます。true／false → ブール値、数値文字列 → 数値、それ以外 → 文字列。フラグを繰り返すと配列を作成できます（例：複数の --images <url>）。--refs <url> が1つだけの場合も、refs は常に配列として送信されます。
• --webhookUrl は input ではなく、リクエストエンベロープのトップレベルに設定されます。
• create に --wait フラグはありません。未知のフラグを指定するとエラーにならず input フィールドとして送信されるため、必ず create と wait を別々の呼び出しとして実行してください。また、taskId を確実に解析できるよう、create では --json を使用してください。
• 納品物は generations 配列に格納されます。各項目には出力の url、mediaType、項目ごとの status／failMsg が含まれます。--json の出力から解析してください。--json を指定しない場合、wait／get は最初の生成結果のみの概要を人間向けに出力するため、複数の出力結果が切り詰められます。ユーザーには URL を渡してください。それ以前の処理（taskId、ポーリング）は単なる内部処理なので、説明する必要はありません。

クレジットとチャージ

クレジットは生成ごとに消費されます。事前に pollo account status（availableCredits）と pollo generate cost … を比較して、実行可能か確認してください。

クレジットが不足している場合（availableCredits がコストを下回っているとすでに確認できる場合、または generate create が insufficient credits — recharge at <url> で失敗した場合のどちらの場合も）、それ以上処理を続けないでください。モデルの切り替え、再試行、ループは行わないでください。ユーザーに不足しているクレジット数を伝え、チャージページ <host>/pricing を案内してください。<host> はログイン中の環境を指します（pollo profile current で確認できます。例：https://pollo.ai/pricing）。「チャージしてください」と伝えるだけでなく、実際のリンクを必ず提示してください。

実行例

pollo account status
pollo model list --type text2image
pollo model get google/nano-banana --fields

# Text-to-video
pollo generate create bytedance/seedance-2-0-fast \
  --prompt "a red sports car drifting on a mountain road" \
  --aspectRatio 16:9 --duration 5 --json

# Text-to-image (endpoint auto-resolved to /image for an image-only model)
pollo generate create pollo-ai/pollo-image-v2 \
  --prompt "a cozy cabin in a snowy forest, warm light" --aspectRatio 16:9 --json

# Image-to-image (image field = local path, uploaded automatically; or an HTTPS URL)
pollo generate create google/nano-banana \
  --image ./photo.png --prompt "make it nighttime" --aspectRatio 1:1 --json

# Reference-to-video: refs on the video endpoint (repeat --refs for multiple).
# Only refs-capable models accept it — confirm `refs` shows up in model get --fields.
pollo generate create vidu/viduq3 \
  --refs ./character.png --prompt "the character walks into frame" --json

# Dual-output model (both /video and /image): pick with --type
pollo generate create kling-ai/kling-v3-omni --type image --prompt "..." --json

pollo generate cost pollo-ai/pollo-image-v2 --prompt "..." --aspectRatio 16:9
pollo generate wait <taskId>
pollo generate get <taskId>        # one-shot status check, no polling

失敗した場合

• クレジット不足（insufficient credits — recharge at … が表示される場合、または availableCredits が generate cost を下回っていることを確認できる場合）— モデルの問題ではなく、処理を終了してください。 モデルの切り替えや再試行はしないでください。ユーザーにチャージリンク <host>/pricing と必要な追加クレジット数を伝えてください。「クレジットとチャージ」を参照してください。
• 403 "This model is not enabled for API access." — model get や generate cost は成功する場合がありますが、そのモデルはこのアカウント／環境では公開されていません。ステップ1に戻って別のモデルを選び、再試行してください。
• その他のサーバー検証エラー — pollo model get <brand>/<alias> --fields を再実行し、該当するフィールド／値を、返された fields／constraints と照らし合わせて確認してください。input の内容が、モデルで実際に宣言されているものと一致していません。
• トークンの期限切れ／無効 — pollo auth login を再実行してください。これは長期間有効なリフレッシュトークン自体が期限切れになった場合にのみ必要です。有効期間の短いトークンは自動で更新されます。
• ローカル画像のアップロード中に生成が失敗する（/file/sign 403） — 一部のアカウントではアップロード手順が制限されています。画像フィールドにはローカルパスではなく、既存の HTTPS 画像 URL を渡してください。
• generate list はサーバーの生の履歴形式を返します（常に JSON）。型付きの結果としてフィールドを解析するのではなく、ざっと確認する不透明な履歴として扱ってください。

その他

pollo --help ／ pollo <command> --help では、グローバルフラグ（--profile、--json、…）やプロファイル管理（pollo profile list|use|current|remove）を含む、すべてのフラグを確認できます。リクエストボディの create ／ cost では { "input": { ...your --name value... }, "webhookUrl"? } を組み立て、/v1/generation/{brand}/{model}/{video|image}（コストの場合は /estimate）に送信します。内容はそのエンドポイントの fields ／ constraints に照らして検証されます。これは、事前に model get --fields で確認できるデータと同じです。

同じ機能は MCP（ローカルの stdio サーバー）経由でも利用でき、Cursor や Claude Desktop などのターミナル以外のエージェントクライアントにも対応しています。ログイン方法と /v1 エンドポイントは同じで、ツールは pollo_list_models（モデルの入力フィールドを確認するには format: 'fields' を渡します）／pollo_estimate_generation_cost ／ pollo_generate_image ／ pollo_generate_video ／ pollo_get_generation_status です。画像入力にはローカルパス（自動でアップロード）または HTTPS URL も指定できます。別途アップロード用のツールはありません。このスキルでは CLI を直接操作するため、ここではこれらのツールを呼び出しません。クライアントの設定については、README の「MCP サーバーとして使用する」をご覧ください。