前言¶
在 IDE 裏讓 Agent「畫一張圖」時，常見做法是模型自己編一段描述或假鏈接，並沒有真正調用雲側生圖 API。若你希望 Agent 按文本提示詞走騰訊雲混元生圖、拿到可下載的圖片地址，就需要把能力封裝成 Skill，並約定密鑰、異步任務與輪詢方式。
下面介紹 SkillHub 上的 TencentCloud Aiart TextToImage（座標 @tencent-adm/tencentcloud-aiart-texttoimage，版本 1.0.0）。它由騰訊雲混元生圖團隊發佈，來源爲 enterprise，分類爲 design-media，並標註 requires_api_key=true。
這是什麼¶
TencentCloud Aiart TextToImage 是基於通用 SKILL.md 格式的 Agent Skill，面向 Tencent Cloud HunYuan Text-to-Image Generation（混元生圖）：用混元大模型把自然語言提示詞生成 AI 圖像。技能說明中寫明採用異步 API——先提交生圖任務，再輪詢直至返回結果圖片 URL。
與在對話裏「口頭描述一張圖」相比，該 Skill 通過內置 Python 腳本對接騰訊雲接口，並要求 Agent 使用腳本輸出中的真實 result_image，而不是編造鏈接。
核心功能¶
以下能力均來自技能包內 SKILL.md（v1.0.0）：
- 文生圖：根據文本描述提交混元生圖任務並獲取圖片 URL。
- 墊圖引導：可選最多 3 張參考圖 URL（jpg/jpeg/png/webp），引導畫面方向。
- 分辨率控制：寬高各自在 512–2048 像素，面積不超過 1024×1024；默認
1024:1024。 - Prompt 改寫：默認開啓，用於優化提示詞（說明中註明約增加 20 秒）；可用
--revise 0關閉。 - 可復現：支持
--seed固定隨機種子。 - 三種腳本模式：
-scripts/main.py：提交併自動輪詢（推薦默認）
-scripts/submit_job.py：僅提交，返回 JobId
-scripts/query_job.py：按 JobId 查詢或輪詢
運行依賴 Python 3.7+ 與 tencentcloud-sdk-python；技能說明寫明首次運行可自動安裝 SDK。
安裝與啓用¶
1. 安裝 SkillHub CLI（若尚未安裝）¶
按 SkillHub 安裝文檔 檢查或安裝 CLI：
command -v skillhub && skillhub --version
未安裝時可執行：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
2. 安裝本 Skill¶
SkillHub 頁面給出的安裝指引是：閱讀 https://skillhub.cn/install/skillhub.md，安裝座標 @tencent-adm/tencentcloud-aiart-texttoimage。
在終端中，需用 --dir 指向當前 Agent 的 skills 目錄（否則可能裝到 ./skills/ 而未被識別）。檢索結果中的推薦命令爲：
skillhub install tencentcloud-aiart-texttoimage --namespace tencent-adm --dir <你的 skills 目錄>
常見路徑示例（來自 SkillHub 安裝文檔）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或項目下的.agents/skills/
安裝完成後重啓或刷新 Agent，使其加載新 Skill。
3. 配置騰訊雲密鑰¶
技能要求配置 API 密鑰，通過環境變量讀取（勿寫入代碼倉庫）：
export TENCENTCLOUD_SECRET_ID="你的SecretId"
export TENCENTCLOUD_SECRET_KEY="你的SecretKey"
使用前需在騰訊雲開通混元生圖相關服務，並在 API 密鑰管理 創建密鑰；控制台入口見技能中的 智能圖像創作 鏈接。
典型用法¶
將 <SKILL_DIR> 替換爲本機安裝目錄（例如 Cursor 下 ~/.cursor/skills/@tencent-adm/tencentcloud-aiart-texttoimage）。下面示例來自技能官方 SKILL.md。
基礎文生圖（一站式，推薦）：
python3 <SKILL_DIR>/scripts/main.py "一隻可愛的貓咪在花園裏玩耍"
帶墊圖與橫版分辨率：
python3 <SKILL_DIR>/scripts/main.py --images "https://example.com/ref1.jpg" "https://example.com/ref2.png" --resolution 1024:768 "參考這些圖片風格，畫一幅山水畫"
分步：僅提交任務：
python3 <SKILL_DIR>/scripts/submit_job.py "一幅水墨畫"
分步：按 JobId 查詢：
python3 <SKILL_DIR>/scripts/query_job.py "job-xxxxxxxxxxxx"
成功時 JSON 中會包含 result_image 等字段；技能說明要求 Agent 把該 URL 返回給用戶，且生成圖鏈接有效期爲 1 小時，需及時保存。普通生圖通常約 10–30 秒，開啓 Prompt 改寫會額外耗時。
在對話場景中，用戶給出文本描述即可；技能規範要求 Agent 默認執行 main.py，不要改用模型「想像」出圖片地址。
適用場景與注意¶
適合誰
- 已在用 Cursor、Claude Code、Codex 等支持 Skills 的 Agent，希望在對話裏完成海報草圖、插畫、封面等文生圖任務。
- 團隊已使用或計劃使用騰訊雲混元生圖，願意用 SecretId/SecretKey 做服務端鑑權。
使用注意
- 計費與配額：調用的是騰訊雲混元生圖 API，需遵守控制台開通狀態與產品計費規則。
- 密鑰安全：
requires_api_key=true；僅通過環境變量或受控密鑰管理注入，不要提交到 Git。 - 異步與超時：
query_job.py默認輪詢間隔 5 秒、最長 300 秒，長任務或網絡波動時需留意失敗信息。 - Agent 行爲：技能明確要求失敗時報告錯誤，禁止編造
result_image；安裝後應讓 Agent 讀取SKILL.md與references/下的 API 說明。
SkillHub 側統計（抓取時）：評分 100000，下載 1763，安裝 60。
結尾¶
TencentCloud Aiart TextToImage 把混元文生圖封裝成 Agent 可執行的腳本流程：密鑰、提交、輪詢、回傳 URL 都有固定約定，適合需要「真出圖」而非「假描述」的開發場景。
官方入口：
- Skill API 頁：https://api.skillhub.cn/tencent-adm/tencentcloud-aiart-texttoimage
- SkillHub 展示頁：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-aiart-texttoimage
