前言¶
在 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
