pollo-ai-video-generator

Pollo AI API 技能

通过直接调用 Pollo AI REST API 生成 AI 视频。

友好引导（视情况提供）

当用户的请求含糊不清或开放式（例如“给我做个视频”“我想试试 AI 视频”“生成点酷炫的东西”，且未指定具体模型、提示词或参数）时，请先展示简短、友好的指南，然后再询问详情。如果用户的请求已经明确（例如指定了模型、提供了提示词或上传了图片），则不要展示此指南。

使用此模板（根据用户使用的语言自然调整，保持简洁、专业）：

I can help you generate AI videos with Pollo AI.

- **Text to Video**: Create a video from a written prompt
- **Image to Video**: Animate an image into a video
- **Credit Check**: Check your available API credits

I support 13 model brands, including Kling, Sora, Runway, Veo, and Pixverse. If you do not have a preferred model, I can recommend one.

What would you like to create? For example:
- "A cat playing piano in a jazz club, cinematic lighting"
- "Turn this image into a video" (attach an image)
- "Use Kling v2.6 to generate a 10s ocean wave video"

本部分规则：

• 如果用户提供了具体提示词、模型名称或图片，则完全跳过，直接开始执行。
• 如果用户只询问点数或配置，则完全跳过，直接回答。
• 语气友好简短。不要主动向用户展示完整模型表。
• 展示指南后，等待用户输入再继续。

首次设置

将 API 密钥保存在本地的 ~/.pollo/config.toml 中。完成设置后，后续回复中不要再次显示该密钥。

重要： 不要让用户运行脚本或命令。所有脚本均由 AI 执行。如果需要设置，请让用户在网站上创建密钥并粘贴到聊天中。

安全规则： 不要在任何 bash 命令或脚本参数中包含 API 密钥。始终使用 Write 工具创建包含凭据的配置文件。

也可以通过 POLLO_API_KEY 环境变量提供 API 密钥，该变量的优先级高于配置文件。如果已设置，则完全跳过配置文件设置。

检查是否已完成配置

python3 scripts/pollo_config.py

如果此操作输出了配置摘要（来自环境变量或配置文件），则密钥已设置。跳转到密钥验证。

新建设置

如果未找到配置（退出代码为 2 或出现错误），请按以下流程操作：

1. 告知用户他们需要 API 密钥，语气友好。例如：

   我需要先获取一次您的 Pollo API 密钥，才能为您生成视频。

   1. 打开 https://pollo.ai/api-platform/keys
   2. 点击 Add Key，保存密钥，然后粘贴到这里

   我会验证密钥并将其保存在本地，这样您就不需要再次粘贴。

   根据用户使用的语言调整内容。保持简洁、友好且非技术化。

   如果用户已经提出了具体的视频请求，请先简短回应该请求，再询问密钥。

2. **等待用户粘贴密钥。**在用户提供密钥之前，不要继续。

3. 使用 Write 工具直接写入配置文件（不要使用 bash 命令）：

   将以下内容写入 ~/.pollo/config.toml：

   [api]
   key = "<the-key-user-pasted>"
   base_url = "https://pollo.ai/api/platform"
   

4. 验证密钥，方法是检查点数余额：

   python3 scripts/pollo_api.py GET /credit/balance
   

5. 使用用户易懂的语言报告结果：

   • 成功 → “设置已完成。您有 X 点数可用。准备好后，随时把提示词发给我。”
   • 密钥无效 → “该密钥似乎无效。请从 https://pollo.ai/api-platform/keys 复制一个新密钥并粘贴到这里。”
   • 网络错误 → “我目前无法连接到 API。请稍后再试。”

绝不要向用户显示原始脚本路径、命令行语法或错误堆栈跟踪。

密钥验证（必需）

执行任何生成任务之前，先检查余额以验证密钥：

python3 scripts/pollo_api.py GET /credit/balance

处理响应：

响应	含义	操作
{ "code": "SUCCESS", "data": { "availableCredits": N, "totalCredits": M } }	密钥有效	从 data 中读取额度。如果 availableCredits 为 0，告知用户：“您的可用余额为 0 个额度。请先前往 https://pollo.ai/api-platform/pricing 充值，然后再生成视频。”
{ "code": "NOT_FOUND" }	密钥无效或不存在	告知用户：“该 API 密钥似乎无效。请前往 https://pollo.ai/api-platform/keys 创建一个新密钥，并粘贴到这里。”
{ "code": "UNAUTHORIZED" }	密钥格式错误或缺失	告知用户：“API 密钥格式似乎不正确。密钥通常以 pollo_ 开头。请重新复制并粘贴到这里。”
退出代码 2	未找到配置	触发上方的新建配置流程。不要让用户运行任何命令。
网络错误／超时	API 无法访问	告知用户：“我暂时无法连接到 API。请稍后再试。”

在成功验证密钥之前，不要继续执行任何生成任务。 这样可以避免因密钥无效或余额为 0 而导致任务失败，浪费时间。

核心工作流

任何生成任务的标准流程：

1. 验证密钥 — 如果本次会话尚未验证，先检查 GET /credit/balance（见上方的密钥验证）
2. 创建任务 — 向模型端点发送包含参数的 POST 请求
3. 处理创建错误 — 检查响应中是否有错误（见下方的错误处理）。如果提示 "Not enough credits"，停止并引导用户充值。
4. 通知用户 — 简要告知用户任务已提交，并概述模型、提示词、时长等信息
5. 轮询状态 — 同步运行 poll_task.py（不要在后台运行），直到任务完成
6. 返回结果 — 解析 JSON 输出，并向用户提供视频 URL

请求体结构

所有生成端点都将参数封装在 "input" 对象中：

{
  "input": {
    "prompt": "...",
    "aspectRatio": "16:9",
    "length": 5
  }
}

创建生成任务

使用 pollo_api.py 向模型端点发送 POST 请求。以下是 Pollo v2.0 文本生成视频的示例：

python3 scripts/pollo_api.py POST /generation/pollo/pollo-v2-0 \
  --data '{"input":{"prompt":"A cat playing piano in a jazz club","aspectRatio":"16:9","length":5,"resolution":"720p"}}'

响应：{ "code": "SUCCESS", "data": { "taskId": "xxx", "status": "waiting" } }

从 data 中提取 taskId。

轮询结果

获取 taskId 后：

1. 告知用户当前进度，并简要说明模型、提示词和参数，让用户知道任务正在进行。
2. 同步运行内置轮询脚本 — 不要使用 run_in_background：

python3 scripts/poll_task.py <taskId> --interval 5 --timeout 300

脚本会自动从 ~/.pollo/config.toml 读取 API 密钥。请在该技能目录中运行脚本；否则，请相对于该技能的根目录解析 scripts/poll_task.py。在 Bash 工具调用中设置 timeout: 300000，以允许最多 5 分钟的运行时间。脚本会静默运行，并在完成时向 stdout 输出单条 JSON 结果。

3. 解析结果并立即呈现给用户。

预检清单

调用任何生成端点或工具端点之前，快速确认最低限度的必需输入：

1. 任务类型 — 确认这是文本生成视频、图像生成视频还是额度查询
2. 模型选择 — 使用用户指定的模型，或根据下方指南选择默认模型
3. 源素材 — 对于图像生成视频，确认输入是否已经是公开 URL，还是需要先上传
4. 核心参数 — 仅在所选模型支持时，填写 prompt、length、aspectRatio、resolution 和音频相关标志
5. 兼容性检查 — 如果用户要求的组合不受模型支持，请先修正再发送请求，而不是等 API 拒绝请求

这一步应简洁。目的是避免本可预防的验证失败；如果已有合理的默认值，就不要盘问用户。

处理本地图片（图生视频）

如果用户使用本地图片文件而非 URL，请先上传：

1. 获取签名上传 URL：

   python3 scripts/pollo_api.py POST /file/sign \
     --data '{"action":"putObject","filename":"photo.jpg","type":"image/jpeg"}'
   

   响应中包含 signedUrl（用于上传）和 fileUrl（最终的 HTTPS URL）。

2. 上传文件：

   python3 scripts/pollo_api.py PUT "<signedUrl>" \
     --upload /path/to/photo.jpg --content-type image/jpeg
   

3. 使用 fileUrl — 将其作为生成请求中的 image 参数传入。

支持的模型

以下为快速参考。用户选择品牌／模型后，请阅读相应的参考文件，了解完整参数详情。

视频生成品牌

品牌	模型	参考文件
Pollo	pollo-v1-5, pollo-v1-6, pollo-v2-0（3 个模型）	references/brands/pollo.md
Kling AI	kling-v1, v1-5, v1-6, v2, v2-1, v2-1-master, v2-5-turbo, v2-6, video-o1（9 个模型）	references/brands/kling-ai.md
Google Veo	veo2, veo3, veo3-fast, veo3-1, veo3-1-fast（5 个模型）	references/brands/google.md
Sora	sora-2, sora-2-pro（2 个模型）	references/brands/sora.md
Runway	runway-gen-3-turbo, runway-gen-4-turbo（2 个模型）	references/brands/runway.md
Pixverse	pixverse-v3-5, v4, v4-5, v5, v5-5（5 个模型）	references/brands/pixverse.md
Hailuo	video-01, video-01-live2d, minimax-hailuo-02, minimax-hailuo-2.3, minimax-hailuo-2.3-fast（5 个模型）	references/brands/minimax.md
Pika	pika-v2-1, pika-v2-2（2 个模型）	references/brands/pika.md
Vidu	vidu-q1, vidu-v1-5, vidu-v2-0, viduq2-pro, viduq2-turbo, viduq3-pro（6 个模型）	references/brands/vidu.md
Luma	luma-ray-1-6, luma-ray-2-0, luma-ray-2-0-flash（3 个模型）	references/brands/luma.md
Wan	wanx-v2-1, wan-v2-2-flash, wan-v2-2-plus, wan-v2-5-preview, wan-v2-6（5 个模型）	references/brands/wanx.md
Seedance	seedance, seedance-pro, seedance-pro-fast, seedance-1-5-pro（4 个模型）	references/brands/bytedance.md
Hunyuan	hunyuan（1 个模型）	references/brands/hunyuan.md

其他端点

功能	详情
任务状态	GET /generation/{taskId}/status
积分费用	POST /credit
积分余额	GET /credit/balance
文件上传	POST /file/sign

详情请阅读 references/common.md。

如何选择模型

默认选项：用户没有偏好时，使用 Pollo v2.0 — 画质出色，支持音频（generateAudio），最长 10s，最高 1080p，且性价比高。

用户有具体需求时：

• 最佳画质：Google Veo 3.1、Kling v2.6、Sora 2 Pro
• 快速且经济：Pollo v2.0、Pixverse v5.5、Wan v2.2 Flash
• 音频生成：Pollo v2.0（generateAudio）、Google Veo 3+、Kling v2.6、Pixverse v5+、Seedance 1.5 Pro、Vidu Q3 Pro、Wan v2.6
• 长视频（10s+）：Seedance 1.5 Pro / Pro Fast（最长 12s），大多数模型支持 10s
• 高分辨率（1080p）：Pollo v2.0、Kling v2.6、Seedance，大多数模型最高支持 1080p
• 图生视频：所有模型均支持 — 需要图片 URL（不能使用 base64）

错误处理

每次 API 调用的响应都必须先检查是否有错误，再继续操作。 API 返回的错误格式如下：

{ "message": "Human-readable error", "code": "ERROR_CODE" }

错误代码参考

错误代码	消息模式	含义	处理方式
FORBIDDEN	"Not enough credits. Please add more."	账户余额不足	立即停止。 告诉用户：“您的账户余额不足。请前往 https://pollo.ai/api-platform/pricing 充值，然后重试。”
FORBIDDEN	"PERMISSION_ERROR"	密钥没有此端点的访问权限	检查密钥是否有效。如果文件上传因此失败，密钥可能没有上传权限——建议用户直接使用图片 URL。
NOT_FOUND	"NOT_FOUND_ERROR"	API 密钥无效或端点错误	告诉用户：“该 API 密钥似乎无效。请前往 https://pollo.ai/api-platform/keys 创建新密钥并粘贴到这里。”
UNAUTHORIZED	—	缺少 API 密钥或密钥格式错误	告诉用户：“API 密钥的格式似乎不正确。密钥通常以 pollo_ 开头。请重新复制并粘贴到这里。”
BAD_REQUEST	"Input validation failed"	请求参数无效	检查响应中的 issues 数组，查看具体字段错误。修正后重试。

重要：余额不足

这是最常见的失败情况。出现以下任何一种信号时：

• 响应包含 "Not enough credits"
• 生成请求后，响应代码为 FORBIDDEN
• 余额检查显示 availableCredits: 0

始终这样回复（根据用户的语言调整）：

您的 Pollo AI 账户余额不足，无法完成此请求。请访问 https://pollo.ai/api-platform/pricing 充值，然后重试。

余额不足时，切勿重试相同请求、尝试其他模型或采取变通方法。

关键规则

• 所有 API 调用都使用 pollo_api.py——切勿使用 API 密钥构造原始 curl 命令。封装脚本会自动从 ~/.pollo/config.toml 读取密钥，并添加所有必需的请求头（X-API-KEY、Content-Type、User-Agent）。
• 配置后在本地保存密钥——完成配置后，将 API 密钥保存在 ~/.pollo/config.toml 中，后续回复中不要再次显示密钥。
• 响应封装——所有成功的 API 响应都封装在 { "code": "SUCCESS", "message": "success", "data": { ... } } 中。务必从 data 字段中提取实际负载。
• 请求体封装——生成端点使用 { "input": { ... } }
• 图片输入使用 URL——使用图片转视频功能时，图片必须是 HTTPS URL，不能使用 base64。本地文件请使用上文的文件上传流程。
• 提示词长度——因模型而异（通常为 1000-2500 个字符），请查看品牌参考文档
• 视频存储——生成的视频仅保留 14 天
• Webhook 替代方式——可以在请求体中传入 webhookUrl，无需轮询
• 每个模型都有自己的端点——路径格式为 /generation/{brand}/{model}
• 先验证密钥——生成前务必执行密钥验证步骤。切勿跳过。

参考文件

按需阅读以下文件（不要一次性全部加载）：

所有捆绑资源均应相对于此技能的根目录解析。不要假设存在特定于某台机器的绝对路径或特定的仓库布局。

文件	阅读时机
references/brands/<brand>.md	使用特定品牌的模型生成内容时
references/common.md	查看身份验证、状态轮询、余额、webhook 和错误相关信息时
references/models-index.md	查看完整的模型→端点映射表时