agnes-ai-generation

Agnes AI 生成

このスキルを使用して、https://apihub.agnes-ai.com 経由で Agnes のテキスト、画像、動画生成 API を呼び出します。

クイックスタート

1. エンドポイントの詳細、パラメーター、レスポンスフィールドが必要な場合は、references/api.md を読みます。
2. 実際に API を呼び出すときは、curl を手作業で書き直すのではなく、scripts/agnes_api.py を使用します。
3. AGNES_API_KEY、AGNES_API_TOKEN、または APIHUB_AGNES_API_KEY に API キーを設定する必要があります。キーは絶対に出力しないでください。
4. 軽量なライブ検証を行うには、smoke-test を実行します。デフォルトでは動画を作成しません。画像から画像を生成する場合は --include-image-edit を追加し、動画モードを検証する場合は --video-case <case> を明示的に追加します。基本的なテキスト生成、テキストストリーミング、テキストのツール呼び出し、テキストから画像への生成、画像から画像への生成、テキストから動画への生成、画像から動画への生成、複数画像からの動画生成、キーフレーム動画生成、動画の取得がすべて成功した場合にのみ、スキルのテストが完全に完了したものとして扱います。

コマンド

テキスト生成：

python scripts/agnes_api.py text --prompt "Write a concise product tagline for an AI assistant."

テキストのストリーミング：

python scripts/agnes_api.py text --prompt "Write a short product intro." --stream

ストリーミング出力は正規化され、集約された content、events、done、短い raw_prefix が含まれます。

画像生成：

python scripts/agnes_api.py image --prompt "A luminous floating city above a misty canyon at sunrise, cinematic realism" --size 1024x768

画像から画像への生成：

python scripts/agnes_api.py image --prompt "Turn the scene into a rainy cyberpunk night while preserving composition" --image https://example.com/input.png --size 1024x768

ポーリングを使用したテキストから動画への生成：

python scripts/agnes_api.py video --prompt "A cinematic shot of a cat walking on the beach at sunset" --poll

画像から動画への生成：

python scripts/agnes_api.py video --prompt "Animate subtle camera movement and natural lighting" --image https://example.com/image.png --poll

キーフレーム／複数画像からの動画生成：

python scripts/agnes_api.py video --prompt "Create a smooth cinematic transition between the two keyframes" --image https://example.com/a.png --image https://example.com/b.png --mode keyframes --poll

動画タスクの取得：

python scripts/agnes_api.py video-get video_123456

軽量なライブスモークテスト：

python scripts/agnes_api.py smoke-test

画像編集のスモークテスト：

python scripts/agnes_api.py smoke-test --include-image-edit

単一動画のスモークテスト：

python scripts/agnes_api.py smoke-test --video-case text-to-video

ワークフロー

• テキストチャット／補完には agnes-2.0-flash を優先してください。
• 自律的なツールワークフローでは、Agnes Responses API のマルチターン関数呼び出しを使用しないでください。ライブテストでは、プロバイダーが全体の status=completed とともに function_call を返す場合があり、previous_response_id を指定して function_call_output を送信すると失敗する可能性があることが確認されています。テキスト生成には、このスキルのチャット補完経路を使用し、ツール呼び出しはリクエスト形式の互換性を最善の範囲で確認するためだけのものとして扱ってください。
• テキストから画像への生成、画像から画像への生成、高情報密度の画像生成には agnes-image-2.1-flash を優先してください。高密度生成ではプロンプトによる指定が重要です。主題の優先順位、環境、細部、照明、構図、品質要件を含めてください。
• テキストから動画への生成、画像から動画への生成、複数画像からの動画生成、キーフレームアニメーション、プロンプトによる動きやシーンの制御、映画品質の出力、非同期タスクの作成、ポーリングによる結果の取得、シード値による再現性には agnes-video-v2.0 を優先してください。
• 画像や動画を生成する場合、画像／動画 API を呼び出す前に、ユーザーからの英語以外のプロンプトを流暢な英語の生成プロンプトに変換してください。英語のプロンプトのほうが Agnes の動画生成では安定します。翻訳時には、具体的な視覚的詳細、スタイル、照明、構図、動き、カメラへの指示、制約を維持してください。
• 動画 API は非同期であることに注意してください。まずタスクを作成し、作成レスポンスに video_id が含まれている場合は、その値でポーリングするか動画を取得します。video_id がない場合に限り、スクリプトは従来の task_id による検索にフォールバックします。
• スクリプトは、リクエストの送信前に画像サイズ、動画のフレーム数、フレームレート、寸法を検証します。num_frames は 8n + 1 を満たし、<= 441 である必要があります。短い値としては 81 または 121 が適しています。
• 安定性を高めるため、動画コマンドのデフォルト値は num_frames=121、frame_rate=24 です。動画のスモークテストでは、デフォルト値が num_frames=81、frame_rate=24 です。
• ユーザーがテストまたは動画生成を明示的に依頼していない限り、コストが高い、または時間がかかるライブ動画生成の前に警告してください。
• 多数のタスクを一度に作成しないよう、動画機能は smoke-test --video-case <case> を使用して一度に1つずつテストしてください。サポートされているケースは text-to-video、image-to-video、multi-image、keyframes です。

現在の検証状況

• ローカルで確認済み：スキルのメタデータ検証と Python の構文。
• ライブ API で確認済み：基本的なテキスト、ストリーミングテキスト、ツール呼び出しリクエストの形式、テキストから画像への生成、画像から画像への生成、情報密度の高いテキストから画像への生成、画像／動画用の中国語プロンプト翻訳、完了したテキストから動画への生成 URL の取得、完了した画像から動画への生成 URL の取得。
• 注意：Agnes はツール呼び出しのリクエストパラメーターを受け付けても、常に tool_calls を返すとは限りません。厳密なツール呼び出しの検証が必要な場合は、smoke-test --strict-tools を使用してください。
• 注意：Agnes Responses API の複数ターンにわたる関数呼び出しは、エージェントのツールループでは信頼性が低いため、Codex／Claude 形式の自動ツール継続には依存しないでください。
• スクリプトとスモークテストセレクターではサポートされていますが、直近の検証ではエンドツーエンドで再実行していません：複数画像からの動画生成とキーフレームアニメーション。
• まだエンドツーエンドで確認できていません：複数画像からの動画生成タスクとキーフレームアニメーションタスクすべてについて、完了後に URL を取得すること。以前、テキストから動画への生成タスクでプロバイダー側の division by zero エラーが発生したため、動画の再試行は見える形で行い、プロバイダーのエラーを明確に報告してください。

出力の処理

• デフォルトでは、生成された画像／動画の URL をそのまま返してください。ユーザーがローカルファイルまたは視覚的な確認を明示的に求めない限り、生成メディアをダウンロード、保存、開く、または確認しないでください。
• 画像のレスポンスでは、extra_body.response_format が url の場合、URL 形式の結果が返されます。
• 動画のレスポンスでは、status が completed の場合に video_url、url、または remixed_from_video_id から URL を抽出してください。
• 動画の取得には、GET /agnesapi?video_id=...&model_name=agnes-video-v2.0 を優先してください。従来の GET /v1/videos/{task_id} も代替手段として引き続き使用できます。
• リクエストに失敗した場合は、API キーを公開せずに HTTP ステータスとプロバイダーのエラーボディを報告してください。