pollo-generate

pollo-generate

pollo-cli 已负责身份验证、令牌刷新和请求构造。你的工作从下一步开始：选择合适的模型，了解其输入字段，构造有效的 input，提交请求，然后返回结果。以下所有步骤都按此顺序进行——模型、输入、提交、结果——因为服务端也按此顺序验证，所以跳过某一步只会在后续某一步导致服务端错误。

设置（每个会话一次）

1. 如果 $PATH 中没有 pollo，请安装已发布的二进制文件——不要从源代码构建：

   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 配置文件。配置文件允许一台设备保存多个登录信息；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[] 数组。能力是一种输入模式——text2video | image2video | ref2video | text2image | image2image——每种能力都有自己的 path（输出端点，即 /video 或 /image），以及自己的 fields/constraints。因此，同时接受文本和图片的模型会有多个共享同一 path 的能力；而像 kling-v3-omni 这样的双输出模型，其能力则覆盖这两个端点。

model list/get 中的 --type 会按能力（上述值）筛选。不要将它与 generate create/cost 中的 --type 混淆，后者表示输出端点（video|image）——请参阅步骤 3。

model get --fields（与 --json 输出相同）会为每个端点返回一条记录，并将其展开为：

• fields[] — {name, type, description, values?, min?, max?}。values 是枚举选项；min/max 用于限定数值字段的范围。
• constraints[] — {id, message, expr}，表示一条针对最终 input 的布尔规则（例如，某个字段仅在特定模式下有效）。如果你计划使用的 input 不符合其中一条规则，message 会告知你提交前需要修改什么，而不是等到收到 400 错误时才发现。

输入模式是一种能力，但它不是独立端点——在请求时，系统会根据你放入 input 的字段来判断模式：只有 prompt → 文本驱动；image → 图片驱动；refs → 参考素材驱动。因此，“此模型是否支持参考素材？”等同于“它是否具有 fields 中包含 refs 的 ref2video 能力？”——请检查，不要猜测。如果模型同时提供 /video 和 /image 路径，请选择符合用户意图的路径，并且只根据对应能力的 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 各自对不同的提示词结构响应最好，在 Veo 上使用 Seedance 风格的提示词（反之亦然）往往效果不佳。

步骤 2 — 准备输入

图片／视频字段（通常为 image、images 或 refs）接受本地文件路径或 HTTPS URL——你无需自行上传。传入本地路径时，CLI 会在生成过程中将其上传到 Pollo 存储，并在提交前替换为生成的 URL；传入托管的 HTTPS URL 则会直接使用。（不接受 base64。）没有单独的上传命令——上传只会作为 generate create/cost 中的一个步骤执行。

第 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>，refs 也始终会以数组形式发送。
• --webhookUrl 会被提取到请求信封的顶层，而不是放入 input。
• create 没有 --wait 标志——未知标志会作为 input 字段发送，而不是报错，因此务必先调用 create，再单独调用 wait；并在 create 时使用 --json，以便可靠地解析 taskId。
• 交付内容位于 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}（cost 使用 /estimate）。请求体会根据该端点的 fields/constraints 进行验证——这些数据也会由 model get --fields 提前显示。

这些功能也通过 MCP（本地 stdio 服务）提供给 Cursor 或 Claude Desktop 等非终端 Agent 客户端使用——使用相同的登录方式和 /v1 端点，并提供工具 pollo_list_models（传入 format: 'fields' 可读取模型的输入字段）/ pollo_estimate_generation_cost / pollo_generate_image / pollo_generate_video / pollo_get_generation_status。图像输入也可以是本地路径（会自动上传）或 HTTPS URL——无需单独的上传工具。由于此技能会直接驱动 CLI，你无需在此处调用这些工具；客户端设置请参阅 README 中的“Use as an MCP server”。