{"skill":{"slug":"tencentcloud-aiart-texttoimage","displayName":"TencentCloud Aiart TextToImage","summary":"Skill for Tencent Cloud HunYuan Text-to-Image Generation (混元生图). Provides AI image generation from text prompts using the HunYuan large model. Supports refer...","description":"---\nname: TencentCloud Aiart TextToImage \ndescription: >\n  Skill for Tencent Cloud HunYuan Text-to-Image Generation (混元生图). Provides AI image generation\n  from text prompts using the HunYuan large model. Supports reference images (垫图), resolution control,\n  prompt rewriting, and reproducible generation with seed.\n  Use when: generating images from text descriptions, AI art creation, poster/cover design,\n  illustration generation, or any text-to-image tasks.\n  Asynchronous API: submits a generation task and polls for the result image URL.\n---\n# 腾讯云混元生图 Skill\n\n## 功能描述\n\n本 Skill 提供**混元生图**能力，基于腾讯混元大模型，将文本描述快速生成 AI 图像。支持垫图引导、自定义分辨率和 prompt 改写优化。\n\n| 场景       | 脚本              | 说明                          |\n| ---------- | ----------------- | ----------------------------- |\n| 一站式生图 | `main.py`       | 提交任务 + 自动轮询，推荐使用 |\n| 仅提交任务 | `submit_job.py` | 仅提交，返回 JobId            |\n| 仅查询任务 | `query_job.py`  | 根据 JobId 查询/轮询结果      |\n\n### 🎯 选择规则\n\n```\n用户要求生成图片  →  main.py（一站式，最简单推荐）\n用户要求提交后自行查询  →  submit_job.py + query_job.py（分步操作）\n用户已有 JobId 要查结果  →  query_job.py（单独查询）\n```\n\n> 如果用户未指定使用哪种模式，Agent 应默认使用 `main.py` 一站式脚本。\n\n### 支持特性\n\n- **垫图引导**：支持传入最多 3 张参考图片 URL，引导生图方向\n- **自定义分辨率**：宽高在 [512, 2048] 范围内，面积不超过 1024×1024\n- **Prompt 改写**：默认开启，自动优化提示词以获得更好效果（增加约 20s）\n- **可复现生成**：支持 Seed 固定随机种子\n- **自动安装依赖**：首次运行时自动安装所需 SDK\n- **智能凭证检测**：优先从环境变量获取密钥，未配置时提示用户开通\n\n## 环境配置指引\n\n### 密钥配置\n\n本 Skill 需要腾讯云 API 密钥才能正常工作。\n\n#### Step 1: 开通混元生图服务\n\n🔗 **[腾讯云智能图像创作控制台](https://console.cloud.tencent.com/aiart)**\n\n#### Step 2: 获取 API 密钥\n\n🔗 **[腾讯云 API 密钥管理](https://console.cloud.tencent.com/cam/capi)**\n\n#### Step 3: 设置环境变量\n\n**Linux / macOS：**\n\n```bash\nexport TENCENTCLOUD_SECRET_ID=\"你的SecretId\"\nexport TENCENTCLOUD_SECRET_KEY=\"你的SecretKey\"\n```\n\n如需持久化：\n\n```bash\necho 'export TENCENTCLOUD_SECRET_ID=\"你的SecretId\"' >> ~/.zshrc\necho 'export TENCENTCLOUD_SECRET_KEY=\"你的SecretKey\"' >> ~/.zshrc\nsource ~/.zshrc\n```\n\n**Windows (PowerShell)：**\n\n```powershell\n$env:TENCENTCLOUD_SECRET_ID = \"你的SecretId\"\n$env:TENCENTCLOUD_SECRET_KEY = \"你的SecretKey\"\n```\n\n> ⚠️ **安全提示**：切勿将密钥硬编码在代码中。\n\n## Agent 执行指令（必读）\n\n> ⚠️ **本节是 Agent（AI 模型）的核心执行规范。当用户请求生成图片时，Agent 必须严格按照以下步骤自主执行，无需询问用户确认。**\n\n### 🔑 通用执行规则\n\n1. **触发条件**：用户提供了文本描述，且意图为生成 AI 图像。\n2. **零交互原则**：Agent 应直接执行脚本，不要向用户询问任何确认。\n3. **自动选择脚本**：默认使用 `main.py`（一站式），除非用户明确要求分步操作。\n4. **⛔ 禁止使用大模型自身能力替代图像生成（最高优先级规则）**：\n   - Agent 严禁自行编造图像 URL 或描述生成结果。\n   - 如果调用失败，Agent **必须**向用户返回清晰的错误说明。\n\n---\n\n### 📌 脚本一：一站式生图 `main.py`（推荐）\n\n**适用场景**：用户请求生成图片，自动提交并等待结果\n\n```bash\npython3 <SKILL_DIR>/scripts/main.py \"文本描述\"\n```\n\n**可选参数**：\n\n- `--images <URL1> <URL2> ...`：垫图 URL 列表，最多 3 张（jpg/jpeg/png/webp，base64 后 ≤ 10MB）\n- `--resolution <W:H>`：分辨率，默认 `1024:1024`。宽高在 [512, 2048]，面积 ≤ 1024×1024\n- `--seed <N>`：随机种子（正整数，不传则随机）\n- `--revise <0|1>`：Prompt 改写，默认开启(1)。关闭(0)需自行改写 prompt，否则影响效果。改写增加约 20s\n- `--no-poll`：仅提交任务不等待结果（返回 JobId）\n\n**输出示例**：\n\n```json\n{\n  \"job_id\": \"job-xxxxxxxxxxxx\",\n  \"status\": \"success\",\n  \"result_image\": \"https://aiart-xxx.cos.ap-guangzhou.myqcloud.com/xxx.png\",\n  \"revised_prompt\": \"一只可爱的橘色猫咪在充满鲜花的花园里愉快地玩耍，阳光明媚，色彩鲜艳\"\n}\n```\n\n> **注意**：生成图 URL 有效期为 **1 小时**，请及时保存。普通生图通常 10~30 秒完成，开启 Revise 会额外增加约 20s。\n\n---\n\n### 📌 脚本二：仅提交任务 `submit_job.py`\n\n**适用场景**：仅需提交任务获取 JobId，后续手动查询\n\n```bash\npython3 <SKILL_DIR>/scripts/submit_job.py \"文本描述\"\n```\n\n**可选参数**：与 `main.py` 相同（除 `--poll-interval`、`--max-poll-time`、`--no-poll` 外）\n\n**输出示例**：\n\n```json\n{\n  \"job_id\": \"job-xxxxxxxxxxxx\",\n  \"request_id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n  \"message\": \"Task submitted successfully. Use query_job.py to poll for results.\"\n}\n```\n\n---\n\n### 📌 脚本三：查询任务 `query_job.py`\n\n**适用场景**：根据 JobId 查询任务状态和结果\n\n```bash\npython3 <SKILL_DIR>/scripts/query_job.py \"job-xxxxxxxxxxxx\"\n```\n\n**可选参数**：\n\n- `--poll-interval <N>`：轮询间隔秒数，默认 5\n- `--max-poll-time <N>`：最大轮询时间秒数，默认 300\n- `--no-poll`：仅查询一次，不轮询\n\n**输出示例**：\n\n```json\n{\n  \"job_id\": \"job-xxxxxxxxxxxx\",\n  \"status\": \"success\",\n  \"result_image\": \"https://aiart-xxx.cos.ap-guangzhou.myqcloud.com/xxx.png\"\n}\n```\n\n---\n\n### 📋 完整调用示例\n\n```bash\n# 基础生图\npython3 /path/to/scripts/main.py \"一只可爱的猫咪在花园里玩耍\"\n\n# 带垫图引导的生图\npython3 /path/to/scripts/main.py --images \"https://example.com/ref1.jpg\" \"https://example.com/ref2.png\" \"参考这些图片风格，画一幅山水画\"\n\n# 自定义分辨率（横版）\npython3 /path/to/scripts/main.py --resolution 1024:768 \"壮丽的山水画\"\n\n# 固定种子（可复现）\npython3 /path/to/scripts/main.py --seed 42 \"星空下的城堡\"\n\n# 关闭 prompt 改写（不推荐，除非自行改写 prompt）\npython3 /path/to/scripts/main.py --revise 0 \"详细描述的prompt内容...\"\n\n# 仅提交任务\npython3 /path/to/scripts/main.py --no-poll \"一幅水墨画\"\n\n# 查询已有任务\npython3 /path/to/scripts/query_job.py \"job-xxxxxxxxxxxx\"\n\n# 通过 stdin 传入 JSON 参数\necho '{\"prompt\":\"一只猫\",\"images\":[\"https://xxx.jpg\"],\"resolution\":\"1024:1024\"}' | python3 /path/to/scripts/main.py --stdin\n```\n\n### 📐 分辨率说明\n\n| 约束   | 说明                                 |\n| ---- | ---------------------------------- |\n| 宽度范围 | [512, 2048] 像素                     |\n| 高度范围 | [512, 2048] 像素                     |\n| 面积上限 | 宽 × 高 ≤ 1024 × 1024 = 1,048,576 像素 |\n| 默认值  | 1024:1024                          |\n\n常用组合：\n\n| 分辨率       | 比例  | 说明   |\n| --------- | --- | ---- |\n| 1024:1024 | 1:1 | 默认方图 |\n| 768:1024  | 3:4 | 竖版   |\n| 1024:768  | 4:3 | 横版   |\n| 512:1024  | 1:2 | 竖版长图 |\n| 1024:512  | 2:1 | 横版长图 |\n\n### 🖼️ 垫图（Images）说明\n\n- 传入参考图片 URL 列表，用于引导生图方向\n- 最多 **3 张**\n- 支持格式：**jpg、jpeg、png、webp**\n- 每张图片 base64 编码后大小不超过 **10MB**\n\n### ❌ Agent 须避免的行为\n\n- 只打印脚本路径而不执行\n- 向用户询问\"是否要执行图片生成\"——应直接执行\n- 手动安装依赖——脚本内部自动处理\n- 忘记读取输出结果中的 `result_image` URL 并返回给用户\n- 图像生成失败时，自行编造图片 URL\n- 忘记提醒用户图片 URL 有效期为 1 小时\n\n## API 参考文档\n\n详细的参数说明、错误码等信息请参阅 `references/` 目录下的文档：\n\n- [提交生图任务 API](references/submit_text_to_image_api.md)（[原始文档](https://cloud.tencent.com/document/product/1668/124632)）\n- [查询生图任务 API](references/query_text_to_image_api.md)（[原始文档](https://cloud.tencent.com/document/product/1668/124633)）\n\n## 核心脚本\n\n- `scripts/main.py` — 一站式生图，提交任务 + 自动轮询等待结果\n- `scripts/submit_job.py` — 仅提交生图任务，返回 JobId\n- `scripts/query_job.py` — 根据 JobId 查询/轮询任务状态和结果\n\n## 依赖\n\n- Python 3.7+\n- `tencentcloud-sdk-python`（腾讯云 SDK）\n\n安装依赖（可选 - 脚本会自动安装）：\n\n```bash\npip install tencentcloud-sdk-python\n```\n","topics":["Image Generation","Prompt"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":522,"installsAllTime":20,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1772799764445,"updatedAt":1778491751707},"latestVersion":{"version":"1.0.0","createdAt":1772799764445,"changelog":"Initial release of TencentCloud Aiart TextToImage skill:\n\n- Provides text-to-image generation using Tencent Cloud HunYuan model, supporting prompt rewriting, reference images, resolution control, and reproducible results via seed.\n- Includes three main scripts: one-step generation (main.py), submit-only (submit_job.py), and query-by-jobid (query_job.py).\n- Automatically handles dependency installation and credential detection.\n- Supports up to 3 reference images, custom resolutions (within 1024×1024 area), and prompt optimization.\n- Requires Tencent Cloud API credentials set via environment variables.\n- Agents must always invoke scripts for image generation—never fabricate results or image URLs.","license":null},"metadata":null,"owner":{"handle":"neck-cn","userId":"s172ywgxmjx97dsa2kkf2ckbps83mvn1","displayName":"败毒","image":"https://avatars.githubusercontent.com/u/37149246?v=4"},"moderation":null}