Agnes AI 全モーダル生成 Skill

概要

本 Skill は Agnes AI (Sapiens AI) の全生成能力をカプセル化し、CLI スクリプトにより統一的に呼び出します。

テキスト生成: agnes-2.5-flash（Thinking 推論モード対応、$0）
画像理解/Vision: agnes-2.5-flash（OpenAI Vision API 互換、画像内容分析可能）
テキスト→画像/画像→画像: agnes-image-2.5-flash（最新世代、高情報密度最適化；--model agnes-image-2.1-flash で前世代にフォールバック可能）
ビデオエンジン1 (V2.0): agnes-video-v2.0 — テキスト→動画 / 画像→動画 / キーフレームアニメーション、自由なフレームレートと解像度、$0/秒
ビデオエンジン2 (Video 2.5 Flash): agnes-video-2.5-flash — 次世代モデル、text/keyframe/reference の3モード、マルチモーダル参照、期間限定無料 720P；有料アップグレード --model agnes-video-2.5 で 960P/2K とビデオ参照を解除
自動翻訳: 中国語プロンプトを自動的に英語に翻訳してから API を呼び出し
非同期ポーリング: 動画タスクを自動的にポーリングして完了まで待機

前提条件

API Key が設定されていることを確認：
- 優先的に scripts/agnes_client.py にハードコードされた API_KEY を読み取り
- プレースホルダ YOUR_AGNES_API_KEY_HERE の場合は、環境変数 AGNES_API_KEY にフォールバック
- いずれも未設定の場合、コードまたは環境変数に API Key を設定するようユーザーに促します
Python 3.8 以降、標準ライブラリ urllib + json のみで十分、追加依存関係は不要。

CLI コマンド早見表

スクリプトの場所: scripts/agnes_client.py

# テキスト生成
python scripts/agnes_client.py text "あなたのプロンプト"
python scripts/agnes_client.py text "こんにちは" --stream
python scripts/agnes_client.py text "クイックソートを書いて" --thinking  # 2.5 推論モード

# テキスト→画像（agnes-image-2.5-flash、デフォルト 1K；推奨は size + ratio）
python scripts/agnes_client.py image "A futuristic city at sunset, cinematic realism" --size 2K --ratio 16:9
python scripts/agnes_client.py image "月明かりの下を歩く猫"
python scripts/agnes_client.py image "..." --model agnes-image-2.1-flash   # 前世代にフォールバック

# 画像→画像（自動アスペクト比検出 — デフォルトは主参照画像の比率で出力）
python scripts/agnes_client.py image "Transform to cyberpunk night" --image-url "https://...input.png" --image-url "https://...ref.png"

# 画像→画像 + 手動指定 ratio（自動検出なし）
python scripts/agnes_client.py image "Transform to cyberpunk night" --image-url "https://...input.png" --ratio 16:9

# ── ビデオエンジン1：V2.0（自由フレームレート/解像度、$0）──
python scripts/agnes_client.py video "A drone flying over mountains at sunrise" --poll          # テキスト→動画
python scripts/agnes_client.py video "Add motion to this scene" --image-url "https://...frame.png" --poll  # 画像→動画
python scripts/agnes_client.py video --keyframes "https://a.com/1.png,https://a.com/2.png,https://a.com/3.png" --poll  # キーフレームアニメーション

# ── ビデオエンジン2：Video 2.5 Flash（次世代、無料 720P）──
python scripts/agnes_client.py video25 "雨後の未来都市の通り、ネオンサインの反射、映画のようなカメラワーク" --poll          # text テキスト→動画
python scripts/agnes_client.py video25 "人物が自然に振り返り窓辺へ歩く" --first-frame "https://.../f.png" --last-frame "https://.../l.png" --poll  # keyframe 最初と最後のフレーム
python scripts/agnes_client.py video25 "<Picture 1> をキャラクター参照として花畑を走る" --image-url "https://.../char.png" --poll  # reference 画像参照
python scripts/agnes_client.py video25 "<Audio 1> のリズムに合わせて夜景を生成" --audio-url "https://.../music.mp3" --poll  # reference 音声参照
python scripts/agnes_client.py video25 "..." --model agnes-video-2.5 --size 960P               # 有料アップグレード（960P/2K）

# 動画タスクを送信のみで待機しない
python scripts/agnes_client.py video "..." --no-poll
python scripts/agnes_client.py video25 "..." --no-poll

# 動画タスクの状態を確認（V2.5 タスクは --model を推奨）
python scripts/agnes_client.py video-status TASK_ID
python scripts/agnes_client.py video-status TASK_ID --model agnes-video-2.5-flash

# 中国語プロンプトの翻訳
python scripts/agnes_client.py translate "一只猫"

# 画像理解 / Vision（agnes-2.5-flash で画像内容を分析）
python scripts/agnes_client.py vision --image-url "https://example.com/photo.png"
python scripts/agnes_client.py vision --image-url "https://example.com/photo.png" --prompt "この時計のブランドは？"

# スモークテスト（API 接続確認）
python scripts/agnes_client.py smoke-test

完全なワークフロー

テキスト→画像の流れ

ユーザーの中/英プロンプトを受け取る
中国語が含まれ、かつ --no-translate が指定されていない場合、自動的に agnes-2.5-flash で英語に翻訳
POST /v1/images/generations を呼び出す（モデルデフォルト: agnes-image-2.5-flash）
レスポンス data[0].url から画像 URL を抽出
結果をユーザーに返す（URL を表示、または curl/ブラウザで開くよう試みる）

サイズ推奨：テキスト→画像では --size 2K --ratio 16:9 のような「サイズ + アスペクト比」指定で予測可能なサイズを得ることを推奨；サポートされていない正確なサイズ（例：1920x1080）はサーバー側で標準化されるため、自分でトリミングが必要。

画像→画像の流れ

ユーザーが入力画像 URL またはローカルパスを提供したことを確認
必要に応じてプロンプトを翻訳
同じエンドポイントを呼び出し、extra_body.image に入力画像 URL の配列を渡す
生成結果を返す

動画生成の流れ（エンジン選択）

Skill は 2 つのビデオエンジンを内蔵。ニーズに応じて選択：

エンジン	サブコマンド	モデル	特徴	価格
V2.0	`video`	`agnes-video-v2.0`	t2v/ti2vid/keyframes、自由フレームレート (num_frames 8n+1) と解像度	$0/秒
Video 2.5	`video25`	`agnes-video-2.5-flash`（デフォルト）/ `agnes-video-2.5`（有料）	次世代：text/keyframe/reference、参照画像/音声、より制御可能なカメラワーク	flash 期間限定無料

Video 2.5 Flash（video25）ワークフロー：

素材から自動でモードを推測（--mode auto）、明示的に指定も可能：
- text：テキストのみ → メディアパラメータなし
- keyframe：--first-frame / --last-frame（少なくとも1つ）で開始と終了の構図を指定
- reference：--image-url（最大5枚）/ --audio-url（最大3セグメント）；プロンプトで <Picture N> / <Audio N> プレースホルダを使用して素材を参照
POST /v1/videos を送信、パラメータ：mode + seconds("4"~"12") + size(flash は 720P のみ) + aspect_ratio + seed
GET /agnesapi?video_id=<ID>&model_name=agnes-video-2.5-flash をポーリング（keyframe/reference は model_name 必須）
ステータス completed 後、レスポンスから動画 URL を抽出

⚠️ video25 と video のパラメータ体系は完全に異なります：video25 は num_frames/width/height/fps/negative_prompt を受け付けません（400 エラーが返ります）。

動画パラメータ制約（エンジン1 V2.0）

num_frames は 8n + 1 を満たす必要があり、最大 441
デフォルト: num_frames=121, frame_rate=24（約 5 秒）
クイックテストは --num-frames 81（約 3.4 秒）

動画パラメータ制約（エンジン2 Video 2.5）

seconds は文字列 "4"~"12"、デフォルト "5"
size：flash は固定 720P；有料モデル agnes-video-2.5 は 720P/960P/2K から選択可能
aspect_ratio：21:9 / 16:9(デフォルト) / 4:3 / 1:1 / 3:4 / 9:16
flash の制限：参照画像は最大5枚、音声は最大3セグメント、動画参照は非対応（有料版は videos 対応）
実測では 720P 16:9 の出力は約 1280x704

画像理解 (Vision) の流れ

agnes-2.5-flash は OpenAI Vision API 形式のマルチモーダル入力をサポートし、画像内容を分析してテキスト説明を返します。これは「視覚能力のないモデルに目を提供する」ための橋渡しソリューションです。2.5 バージョンの画像理解能力は 2.0 より強力で、詳細認識がより正確です。

画像がパブリックアクセス可能な HTTP(S) URL にアップロードされていることを確認
vision コマンドを呼び出し、画像 URL + オプションの分析プロンプトを渡す
テキスト説明が返され、そのまま他のモデルにコンテキストとして渡すことができます（例：「この画像の時計デザインの改善提案をしてください」— まず vision で説明を取得し、任意のテキストモデルに渡して分析させる）

Vision コマンドパラメータ：

--image-url（必須、複数回指定可能）：分析する画像の URL
--prompt（オプション）：分析プロンプト、デフォルトは "Describe this image in detail."
--system（オプション）：システムプロンプト
--max-tokens（オプション）：最大出力トークン数、デフォルト 1000
--no-translate（オプション）：自動翻訳をスキップ（英語プロンプトの場合は使用を推奨）

プロンプトのベストプラクティス

画像プロンプトの構造

[主題] + [シーン] + [スタイル] + [照明] + [構図] + [品質]

例:

A luxury watch with a black leather strap on a marble surface, soft studio lighting, macro photography, 8K detail, high visual density

画像→画像プロンプト

変更するものと維持するものを明確に記述：

Transform the background to a dark luxury setting while preserving the watch design and angle.

動画プロンプト

カメラワークと時間要素を追加：

A slow 360-degree rotation around the watch, revealing every detail, cinematic lighting, smooth movement

価格

モデル	価格設定
`agnes-2.5-flash` (テキスト/Vision/推論)	無料 ($0/1M tokens)
`agnes-image-2.5-flash` (画像、最新世代)	無料 ($0/画像、全 1K~4K サイズ)
`agnes-image-2.1-flash` (画像、前世代)	無料 ($0/画像)
`agnes-video-v2.0` (ビデオエンジン1)	無料 ($0/秒)
`agnes-video-2.5-flash` (ビデオエンジン2)	期間限定無料 ($0/秒、720P)
`agnes-video-2.5` (動画、有料アップグレード)	$0.025/秒(720P) / $0.040/秒(960P) / $0.055/秒(2K)

価格は公式サイト https://www.agnes-ai.com/zh-Hans/docs/pricing を基準とし、無料ポリシーはプラットフォームの発表に応じて変更される可能性があります。

既知の制限

2.5 Thinking モードは reasoning_content フィールド（思考過程）を返し、出力トークンが若干増加します
動画生成で稀にサーバー側の division by zero エラーが発生
V2.0 の複数画像動画/キーフレームアニメーションはまだ完全にエンドツーエンドで検証されていません
画像 API は入力として HTTP(S) URL のみを受け付け、base64 は非対応（出力は URL または Base64 を選択可能）
agnes-video-2.5-flash は 720P のみで、動画参照は非対応；960P/2K や動画参照が必要な場合は有料の --model agnes-video-2.5 を使用
video25 の keyframe/reference タスクのクエリには必ず --model agnes-video-2.5-flash を付ける必要があります

自動アスペクト比検出（i2i）

i2i 時に --ratio が指定されていない場合、スクリプトは自動的に主参照画像（最初の --image-url）の縦横比を検出し、agnes-image-2.5-flash がサポートする 8 つの公式 ratio のいずれかにマッピングします（1:1 / 3:4 / 4:3 / 16:9 / 9:16 / 2:3 / 3:2 / 21:9）。これにより、出力キャンバスのアスペクト比が入力の主体と一致せず、人物が変形するのを防ぎます。

# 自動検出： [INFO] Main reference image: ... → auto ratio: ... と表示
python scripts/agnes_client.py image "prompt" --image-url MODEL_URL --image-url REF_URL --size 2K

# 手動指定（自動検出をスキップ）
python scripts/agnes_client.py image "prompt" --image-url MODEL_URL --ratio 16:9

主参照画像の取り決め：最初の --image-url が構図/比率を決定する主体（通常はモデル/製品画像）とみなされ、2枚目以降はスタイル/詳細参照と見なされます。主参照画像を切り替えるには、--image-url の順序を入れ替えてください。

参考

API 詳細ドキュメント: references/api_reference.md
公式サイト: https://agnes-ai.com/
API プラットフォーム: https://platform.agnes-ai.com/

Agnes マルチモーダル