Agnes 全模態

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 回退上一代）
• 影片引擎一 (V2.0): agnes-video-v2.0 — 文生影片 / 圖生影片 / 關鍵幀動畫，自由幀率與解析度，$0/秒
• 影片引擎二 (Video 2.5 Flash): agnes-video-2.5-flash — 新一代模型，text/keyframe/reference 三模式，多模態參考，限時免費 720P；付費升級 --model agnes-video-2.5 可解鎖 960P/2K 與影片參考
• 自動翻譯: 中文提示詞自動譯英文後呼叫 API
• 非同步輪詢: 影片任務自動輪詢直到完成

前置條件

1. 確認 API Key 已配置：

   • 優先讀取 scripts/agnes_client.py 中硬編碼的 API_KEY
   • 如為佔位符 YOUR_AGNES_API_KEY_HERE，則回退讀取環境變數 AGNES_API_KEY
   • 若均未配置，提醒用戶在程式碼或環境變數中設定 API Key

2. 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

# ── 影片引擎一：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  # 關鍵幀動畫

# ── 影片引擎二：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 "What brand is this watch?"

# 冒煙測試（驗證 API 連通性）
python scripts/agnes_client.py smoke-test

完整工作流

文生圖流程

1. 接收使用者的中文/英文提示詞
2. 若含中文且未指定 --no-translate，自動呼叫 agnes-2.5-flash 翻譯為英文
3. 呼叫 POST /v1/images/generations（模型預設: agnes-image-2.5-flash）
4. 從回應 data[0].url 提取圖片 URL
5. 將結果返回給使用者（顯示 URL，或嘗試用 curl/瀏覽器打開）

尺寸建議：文生圖推薦 --size 2K --ratio 16:9 這類「檔位 + 比例」寫法以獲得可預期尺寸； 不支援的精確尺寸（如 1920x1080）會被服務端標準化，需自行裁剪。

圖生圖流程

1. 確認使用者提供了輸入圖片 URL 或本地路徑
2. 如需翻譯提示詞，執行翻譯
3. 呼叫同一 endpoint，在 extra_body.image 中傳入輸入圖片 URL 陣列
4. 返回生成結果

影片生成流程（引擎選擇）

Skill 內建兩個影片引擎，按需求選擇：

引擎	子命令	模型	特點	價格
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）工作流：

1. 按素材自動推斷模式（--mode auto），也可顯式指定：
   • text：純文字 → 無任何媒體參數
   • keyframe：--first-frame / --last-frame（至少一個）約束起止構圖
   • reference：--image-url（≤5 張）/ --audio-url（≤3 段）；提示詞用 <Picture N> / <Audio N> 佔位符指代素材
2. 提交 POST /v1/videos，參數：mode + seconds("4"~"12") + size(flash 僅 720P) + aspect_ratio + seed
3. 輪詢 GET /agnesapi?video_id=<ID>&model_name=agnes-video-2.5-flash（keyframe/reference 必須帶 model_name）
4. 狀態 completed 後從回應提取影片 URL

⚠️ video25 與 video 參數體系完全不同：video25 不接受 num_frames/width/height/fps/negative_prompt（會返回 400）。

影片參數約束（引擎一 V2.0）

• num_frames 必須滿足 8n + 1，最大 441
• 預設: num_frames=121, frame_rate=24（約 5 秒）
• 快速測試用 --num-frames 81（約 3.4 秒）

影片參數約束（引擎二 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 更強，細節識別更準確。

1. 確保圖片已上傳到可公網存取的 HTTP(S) URL
2. 呼叫 vision 命令，傳入圖片 URL + 可選的分析提示詞
3. 返回文字描述，可直接作為上下文傳給其他模型（如「請對這張圖片中的手錶設計給出改進建議」——先 vision 獲取描述，再傳給任意文字模型分析）

Vision 命令參數：

• --image-url（必填，可多次指定）: 要分析的圖片 URL
• --prompt（可選）: 分析提示詞，預設 "Describe this image in detail."
• --system（可選）: 系統提示詞
• --max-tokens（可選）: 最大輸出 tokens，預設 1000
• --no-translate（可選）: 跳過自動翻譯（英文 prompt 建議使用）

提示詞最佳實踐

圖片 Prompt 結構

[Subject] + [Scene] + [Style] + [Lighting] + [Composition] + [Quality]

範例:

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

圖生圖 Prompt

明確描述要改變什麼 + 保持什麼:

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

影片 Prompt

加入運鏡和時間元素:

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 (影片引擎一)	免費 ($0/秒)
agnes-video-2.5-flash (影片引擎二)	限時免費 ($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 欄位（思考過程），會增加少量輸出 token
• 影片生成偶有 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 視為決定構圖/比例的主體（通常是模特/產品圖），第二張及以後視為風格/細節參考。如需切換主參考圖，交換 --image-url 順序即可。

參考

• API 詳細文件: references/api_reference.md
• 官網: https://agnes-ai.com/
• API 平台: https://platform.agnes-ai.com/