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 が行います。セットアップが必要な場合は、ウェブサイトでキーを作成してチャットに貼り付けるようユーザーに依頼してください。

セキュリティルール： API キーを bash コマンドやスクリプトの引数に含めないでください。認証情報を含む設定ファイルは、必ず Write ツールを使用して作成してください。

API キーは POLLO_API_KEY 環境変数でも指定できます。この環境変数は設定ファイルより優先されます。設定されている場合は、設定ファイルのセットアップを完全に省略してください。

設定済みか確認する

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 に接続できませんでした。しばらくしてからもう一度お試しください。」と伝えます。

キーの検証に成功するまで、生成タスクを実行しないでください。 これにより、キーが無効または残高不足のために失敗するタスクに時間を費やすことを防げます。

基本的なワークフロー

生成タスクの標準的なフローは次のとおりです。

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 のパスを解決してください。最大 5 分間待機できるように、Bash ツール呼び出しで timeout: 300000 を設定します。スクリプトは何も表示せずに実行され、完了すると単一の 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 と、最終的な HTTPS URL である fileUrl が含まれます。

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）に対応し、最大 10 秒、最大 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
• 長尺動画（10 秒以上）：Seedance 1.5 Pro／Pro Fast（最大 12 秒）、ほとんどのモデルが 10 秒に対応
• 高解像度（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	モデルからエンドポイントへの対応表全体を確認するとき