Back to Details

pollo-generate

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

pollo-generate

pollo-generate

pollo-cli
already owns auth, token refresh, and request shaping. Your job starts one step later: pick the right model, learn its input fields, build a valid 
input
, submit, and hand back the result. Everything below follows that order — model, then input, then submit, then result — because that's also the order the server validates in, so skipping a step just turns into a server error one step later.
pollo-cli
已经负责身份验证、token 刷新和请求封装。你的工作从后一步开始：选择合适的模型、了解其输入字段、构建有效的 
input
、提交任务并返回结果。下面所有内容都遵循这一顺序——模型、输入、提交、结果——因为服务端也按此顺序进行校验；跳过任何一步，只会把问题推迟一步，变成随后出现的服务端错误。

Setup (once per session)

设置（每个会话只需执行一次）

  1. If 
    pollo
    isn't on 
    $PATH
    , install the released binary — don't build from source:
    bash
    npm i -g @pollo-ai/cli
    Without Node (macOS / Linux only), fall back to the standalone installer:
    bash
    curl -fsSL https://raw.githubusercontent.com/polloaiofficial/cli/main/install.sh | sh
  2. Run 
    pollo account status
    . An 
    availableCredits
    number means you're already logged in to prod (
    pollo.ai
    , profile 
    default
    ). A missing/expired token error means:
    bash
    pollo auth login   # opens the browser, logs into pollo.ai -> profile "default"
    The CLI owns its own credential storage and refreshes the short-lived token before each request, so you won't need to log in again mid-session. Never read, print, or copy the stored credentials — every command below authenticates on its own.
  3. Stay on the 
    default
    profile unless the user names another one. Profiles let one machine hold several logins; 
    pollo profile list
    shows them (
    *
    marks current), 
    pollo profile use <name>
    switches, and 
    pollo --profile <name> <command>
    overrides for a single command.
  1. 如果 
    $PATH
    中没有 
    pollo
    ，请安装已发布的二进制文件——不要从源码构建：
    bash
    npm i -g @pollo-ai/cli
    如果没有 Node（仅限 macOS / Linux），请改用独立安装程序：
    bash
    curl -fsSL https://raw.githubusercontent.com/polloaiofficial/cli/main/install.sh | sh
  2. 运行 
    pollo account status
    。如果返回 
    availableCredits
    数值，说明你已经登录生产环境（
    pollo.ai
    ，配置文件为 
    default
    ）。如果出现 token 缺失或过期错误，请执行：
    bash
    pollo auth login   # 打开浏览器，登录 pollo.ai -> 配置文件 "default"
    CLI 会自行管理凭据存储，并在每次请求前刷新短期 token，因此会话中无需再次登录。绝不读取、打印或复制已存储的凭据——以下每条命令都会自行完成身份验证。
  3. 除非用户指定了其他配置文件，否则始终使用 
    default
    。配置文件允许同一台设备保存多个登录身份；
    pollo profile list
    可列出这些配置文件（
    *
    标记当前配置），
    pollo profile use <name>
    用于切换配置，
    pollo --profile <name> <command>
    则可仅为单条命令临时覆盖配置。

Step 1 — Find the model, then read what it actually accepts

第 1 步——查找模型，然后查看它实际接受哪些输入

Never guess a 
brand
/
alias
or a field name — they change as models ship, so a guess just surfaces as a server validation error one step later instead of saving you a lookup now:
bash
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
Each model is listed once, with a 
capabilities[]
array. A capability is an input mode — 
text2video
| 
image2video
| 
ref2video
| 
text2image
| 
image2image
— and each one carries its own 
path
(the output endpoint, 
/video
or 
/image
) plus its own 
fields
/
constraints
. So a model that takes both text and images has several capabilities sharing one 
path
, and a dual-output model like 
kling-v3-omni
has capabilities across both paths.
--type
on 
model list
/
get
filters by capability (the values above). Don't confuse it with 
--type
on 
generate create
/
cost
, which is the output endpoint (
video
|
image
) — see Step 3.
model get --fields
(same output as 
--json
) returns one entry per endpoint, each already flattened to:
  • fields[]
    — 
    {name, type, description, values?, min?, max?}
    . 
    values
    is the enum choices; 
    min
    /
    max
    bound a numeric field.
  • constraints[]
    — 
    {id, message, expr}
    , a boolean rule over the eventual 
    input
    (e.g. a field that's only valid in a certain mode). If your planned 
    input
    would fail one, 
    message
    tells you what to change before you submit instead of finding out from a 400.
The input mode is a capability, but it is not a separate endpoint — at request time it's decided by which fields you put in 
input
: 
prompt
only → text-driven, 
image
→ image-driven, 
refs
→ reference-driven. So "does this model support references?" = "does it have a 
ref2video
capability whose 
fields
include 
refs
?" — check that, don't guess. If a model exposes both a 
/video
and an 
/image
path, pick the one matching the user's intent and build 
input
only from that capability's 
fields
.
If the user hasn't named a specific model, read 
references/model-routing.md
 first — it maps what the user actually said to a concrete 
brand/alias
(video branches for on-screen text / single image / multi-reference / default, quality tiers, and an image routing table), with the fallback chain to use when a generation disappoints. Brands are not guessable (HappyHorse and Wan are 
alibaba/
, Sora is 
openai/
, Grok is 
xai/
, Seedream is 
bytedance/
), so route from that file rather than from memory, and verify with 
model list
before you commit.
Once you know which video model you're using, write the 
prompt
field's wording following that vendor's own formula in 
references/prompt-engineering.md
 — Kling, Veo, Seedance, Sora, Vidu, Wan, and Pixverse each respond best to a different prompt structure, and a Seedance-style prompt on Veo (or vice versa) tends to underperform.
绝不猜测 
brand
/
alias
或字段名——它们会随着模型上线而变化；猜测只会把问题推迟到下一步，以服务端校验错误的形式出现，而不是现在省去一次查询：
bash
pollo model list                        # 列出所有标准模型，并汇总其 capabilities
pollo model list --type text2video      # 仅列出具有该 capability 的模型
pollo model get <brand>/<alias> --fields   # 查看此模型的输入结构
每个模型只列出一次，并带有一个 
capabilities[]
数组。一个 capability 表示一种输入模式——
text2video
| 
image2video
| 
ref2video
| 
text2image
| 
image2image
——每种模式都带有自己的 
path
（输出端点，即 
/video
或 
/image
），以及自己的 
fields
/
constraints
。因此，一个同时接受文本和图像的模型会有多项 capability 共用一个 
path
；而像 
kling-v3-omni
这样的双输出模型，其 capability 会横跨两个 path。
model list
/
get
上的 
--type
根据 capability（上述值）进行过滤。不要将其与 
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 错误后才发现。
输入模式是一种 capability，但它不是单独的端点——请求时，它由你放入 
input
的字段决定：仅使用 
prompt
→ 文本驱动，使用 
image
→ 图像驱动，使用 
refs
→ 参考驱动。因此，“这个模型支持参考输入吗？”等同于“它是否具有一项 
ref2video
capability，且该 capability 的 
fields
包含 
refs
？”——请检查，不要猜测。如果模型同时提供 
/video
和 
/image
path，请选择与用户意图相符的那个，并且只根据对应 capability 的 
fields
构建 
input
。
如果用户没有指定具体模型，请先阅读 
references/model-routing.md
——它会将用户的实际需求映射到具体的 
brand/alias
（包括画面文字、单张图像、多参考图和默认情况下的视频分支、质量等级，以及图像路由表），并提供生成效果不理想时使用的回退链。品牌无法凭记忆猜测（HappyHorse 和 Wan 属于 
alibaba/
，Sora 属于 
openai/
，Grok 属于 
xai/
，Seedream 属于 
bytedance/
），因此应根据该文件进行路由，而不是凭记忆选择，并在确定模型前使用 
model list
进行验证。
确定要使用的视频模型后，请按照对应厂商在 
references/prompt-engineering.md
 中给出的公式撰写 
prompt
字段。Kling、Veo、Seedance、Sora、Vidu、Wan 和 Pixverse 分别对不同结构的 prompt 响应最佳，将 Seedance 风格的 prompt 用于 Veo（或反之）通常会导致效果下降。

Step 2 — Prepare inputs

第 2 步——准备输入

Image/video fields (commonly 
image
, 
images
, or 
refs
) accept either a local file path or an HTTPS URL — you don't upload anything yourself. When you pass a local path, the CLI uploads it to Pollo storage as part of the generation and substitutes the resulting URL before submitting; pass a hosted HTTPS URL and it's used as-is. (base64 isn't accepted.) There is no separate upload command — uploads only happen as a step inside 
generate create
/
cost
.
图像/视频字段（通常为 
image
、
images
或 
refs
）接受本地文件路径或 HTTPS URL——你无需自行上传任何内容。传入本地路径时，CLI 会在生成过程中将文件上传到 Pollo 存储，并在提交前替换为生成的 URL；传入托管的 HTTPS URL 时则原样使用。（不接受 base64。）没有单独的上传命令——上传仅作为 
generate create
/
cost
内部的一步发生。

Step 3 — Submit and read the result

第 3 步——提交并读取结果

bash
undefined
bash
undefined

optional: estimate before an expensive run, or whenever the user is cost-sensitive

可选：在费用较高的运行前估算，或在用户对成本敏感时使用

pollo generate cost <brand>/<alias> [--type video|image] --name value ...
pollo generate cost <brand>/<alias> [--type video|image] --name value ...

-> cost / singleCost / discountCost / discountSingleCost (+ their *Usd counterparts)

-> cost / singleCost / discountCost / discountSingleCost（以及相应的 *Usd 值）

pollo generate create <brand>/<alias> [--type video|image]
--name value ... --json # -> { "taskId": "...", "status": "waiting" }
pollo generate wait <taskId> [--timeout 10m] [--interval 3s] --json
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",

-> { "taskId", "credit", "generations": [{ "status": "succeed|failed",

"url", "mediaType", "failMsg" }] }

"url", "mediaType", "failMsg" }] }


Notes on the flags above:

- You usually don't need `--type`: the CLI resolves the endpoint from
  `/v1/models` on its own. Pass `--type video|image` only when the model
  has both output types (the CLI errors and tells you so), or to skip the
  extra lookup when you already know.
- Every other `--name value` becomes `input.<name>`. Values auto-type:
  `true`/`false` → boolean, numeric strings → number, everything else →
  string. Repeat a flag to build an array (e.g. multiple `--images <url>`);
  `refs` is always sent as an array even from a single `--refs <url>`.
- `--webhookUrl` is lifted to the request envelope's top level, not into
  `input`.
- There is no `--wait` flag on `create` — an unknown flag would be sent as an
  `input` field instead of erroring, so always go through `create` then
  `wait` as two separate calls, and use `--json` on `create` so you can parse
  `taskId` reliably.
- The deliverable lives in the `generations` array: each item carries the
  output `url`, `mediaType`, and per-item `status`/`failMsg`. Parse it from
  the `--json` output — without `--json`, `wait`/`get` print a human summary
  of only the **first** generation, so multi-output results get truncated.
  Hand the user the URL(s); everything before that (taskId, polling) is just
  plumbing you don't need to narrate.

关于上述 flags 的说明：

- 通常不需要使用 `--type`：CLI 会自行从 `/v1/models` 解析端点。仅当模型同时支持两种输出类型时（CLI 会报错并给出提示），或者你已明确知道端点并希望跳过额外查询时，才传入 `--type video|image`。
- 其他每个 `--name value` 都会成为 `input.<name>`。值会自动进行类型转换：`true`/`false` → boolean，数字字符串 → number，其他所有值 → string。重复传入同一个 flag 可构建数组（例如多个 `--images <url>`）；即使只传入一个 `--refs <url>`，`refs` 也始终以数组形式发送。
- `--webhookUrl` 会被提升到请求封装的顶层，而不是放入 `input`。
- `create` 没有 `--wait` flag——未知 flag 不会报错，而是会被当作 `input` 字段发送，因此始终应将 `create` 和 `wait` 作为两次独立调用，并在 `create` 时使用 `--json`，以便可靠地解析 `taskId`。
- 最终交付内容位于 `generations` 数组中：每个条目都包含输出 `url`、`mediaType` 以及各自的 `status`/`failMsg`。请从 `--json` 输出中解析它；如果不使用 `--json`，`wait`/`get` 只会以人类可读形式打印**第一个**生成结果，多输出结果会被截断。将 URL 提供给用户即可；在此之前的 taskId、轮询等都只是无需向用户叙述的内部流程。

Credits & recharge

积分与充值

Credits are spent per generation. Gauge affordability up front by comparing 
pollo account status
(
availableCredits
) with 
pollo generate cost …
.
When the user is short on credits — either you can already see 
availableCredits
is below the cost, or a 
generate create
fails with 
insufficient credits — recharge at <url>
— treat it as terminal: do not switch models, retry, or loop. Tell the user how many more credits they need and point them to the recharge page 
<host>/pricing
, where 
<host>
is the environment you're logged into (
pollo profile current
shows it, e.g. 
https://pollo.ai/pricing
). Always give the actual link, not just "please recharge".
每次生成都会消耗积分。可将 
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
）。始终提供实际链接，不要只说“请充值”。

Worked examples

实操示例

bash
pollo account status
pollo model list --type text2image
pollo model get google/nano-banana --fields
bash
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
pollo generate create bytedance/seedance-2-0-fast
--prompt "一辆红色跑车在山间公路上漂移"
--aspectRatio 16:9 --duration 5 --json

Text-to-image (endpoint auto-resolved to /image for an image-only model)

文生图（对于仅支持图像的模型，端点会自动解析为 /image）

pollo generate create pollo-ai/pollo-image-v2
--prompt "a cozy cabin in a snowy forest, warm light" --aspectRatio 16:9 --json
pollo generate create pollo-ai/pollo-image-v2
--prompt "雪林中的一间温馨小屋，暖色灯光" --aspectRatio 16:9 --json

Image-to-image (image field = local path, uploaded automatically; or an HTTPS URL)

图生图（image 字段可以是本地路径并自动上传，也可以是 HTTPS URL）

pollo generate create google/nano-banana
--image ./photo.png --prompt "make it nighttime" --aspectRatio 1:1 --json
pollo generate create google/nano-banana
--image ./photo.png --prompt "把它改成夜晚" --aspectRatio 1:1 --json

Reference-to-video: refs on the video endpoint (repeat --refs for multiple).

参考图生视频：refs 位于视频端点上（多个参考图需重复传入 --refs）。

Only refs-capable models accept it — confirm 
refs
shows up in model get --fields.

只有支持 refs 的模型才能接受该参数——请确认 model get --fields 中显示了 refs。

pollo generate create vidu/viduq3
--refs ./character.png --prompt "the character walks into frame" --json
pollo generate create vidu/viduq3
--refs ./character.png --prompt "角色走进画面" --json

Dual-output model (both /video and /image): pick with --type

双输出模型（同时支持 /video 和 /image）：使用 --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
undefined
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> # 单次状态检查，不进行轮询
undefined

When it fails

失败处理

  • Insufficient credits (
    insufficient credits — recharge at …
    , or you can see 
    availableCredits
    is below the 
    generate cost
    ) — terminal, not a model problem. Do NOT switch models or retry; give the user the recharge link 
    <host>/pricing
    and how many more credits are needed. See "Credits & recharge".
  • 403 "This model is not enabled for API access."
     — that model isn't exposed on this account/environment, even though 
    model get
    and 
    generate cost
    may still succeed for it. Go back to Step 1, pick a different model, retry.
  • Any other validation error from the server — re-run 
    pollo model get <brand>/<alias> --fields
    and check the offending field/value against the 
    fields
    /
    constraints
    you got back; something in 
    input
    doesn't match what the model actually declared.
  • Expired/invalid token — 
    pollo auth login
    again. This is only needed once the long-lived refresh token itself has expired; the short-lived one refreshes automatically.
  • Generation fails uploading a local image (
    /file/sign
    403)     — the upload step is gated to some accounts. Pass an existing HTTPS image URL for the image field instead of a local path.
  • generate list
     returns the server's raw history shape (always JSON) — treat it as opaque history to skim, not a typed result to parse fields out of.
  • 积分不足（
    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
    中的某些内容与模型实际声明的结构不一致。
  • token 过期或无效——再次运行 
    pollo auth login
    。只有长期有效的 refresh token 本身过期时才需要这样做；短期 token 会自动刷新。
  • 上传本地图像时生成失败（
    /file/sign
    403）    ——上传步骤仅对部分账户开放。请改为为 image 字段传入已有的 HTTPS 图像 URL，不要使用本地路径。
  • generate list
     返回服务端的原始历史记录结构（始终为 JSON）——应将其视为只需快速浏览的不透明历史记录，不要从中解析特定字段。

Everything else

其他信息

pollo --help
/ 
pollo <command> --help
cover the full flag list: global flags (
--profile
, 
--json
, …) and profile management (
pollo profile list|use|current|remove
). The request body 
create
/
cost
build is 
{ "input": { ...your --name value... }, "webhookUrl"? }
, posted to 
/v1/generation/{brand}/{model}/{video|image}
(
/estimate
for cost) and validated against that endpoint's 
fields
/
constraints
— the same data 
model get --fields
shows you up front.
The same capabilities are also exposed over MCP (
pollo mcp
, a local stdio server) for non-terminal agent clients like Cursor or Claude Desktop — same login and 
/v1
endpoints, tools 
pollo_list_models
(pass 
format: 'fields'
to read a model's input fields) / 
pollo_estimate_generation_cost
/ 
pollo_generate_image
/ 
pollo_generate_video
/ 
pollo_get_generation_status
. Image inputs there also take a local path (uploaded automatically) or an HTTPS URL — there's no separate upload tool. As this skill drives the CLI directly you won't call those here; see the README "Use as an MCP server" for client setup.
pollo --help
/ 
pollo <command> --help
包含完整的 flag 列表：全局 flags（
--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 暴露（
pollo mcp
是一个本地 stdio server），供 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——没有单独的上传工具。由于本 skill 直接驱动 CLI，因此这里不会调用这些工具；客户端设置请参阅 README 中的“Use as an MCP server”一节。