下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/org-gydw2je6--zhishu-hyimage.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md，安装 @org-gydw2je6/zhishu-hyimage。- 通过 www.zhishuai.net 网关调用腾讯混元 Hy-Image-3.5-Preview 图片生成 API（Chat/Messages 协议），支持文生图、图生图（文本+参考图）、多轮编辑（assembled_history 回灌）。同步接口，直接返回并保存本地图片。触发场景：用户说"
- 用混元生成图"
- "
- 用 Hy-Image 画图"
- "
- 基于这张图改一改"
- …（完整说明见下方「阅读全文」）
阅读全文 （展开查看完整说明）
概述
混元 Hy-Image-3.5-Preview 图片生成
调用 https://www.zhishuai.net/v1/chat/completions（Chat/Messages 协议），模型 hy-image-v3.5-preview，同步返回图片。
对接文档：本 skill 的接口形态对齐腾讯混元官方文档
【Hy-Image-3.5-Preview 图片生成（文生图 / 图生图 / 多轮编辑）】
（
https://cloud.tencent.com/document/product/1823/135745）。官方规范请求地址为
https://tokenhub.tencentmaas.com/v1/wand/hunyuan-image/v35-generation，www.zhishuai.net 是这套接口的代理/中转，请求地址改用
/v1/chat/completions、请求体保持 Chat/Messages 结构。下文「参数结构」「响应结构」均以官方文档为准。
模型名不带前缀（网关精确匹配
hy-image-v3.5-preview）。脚本resolve_model()原样透传，请勿加bytedance/之类前缀。
触发条件
- 用户要「画 / 生成 / 做一张图」，且上下文是混元 Hy-Image 系列
- 提到模型名：
hy-image-v3.5-preview（或简称「混元生图」「Hy-Image」） - 用户要「基于这张图改 / 加内容」（图生图）、「接着上一张继续改」（多轮编辑）
环境变量（均以 ZHISHUAI_HYIMAGE_ 为前缀，可选）
| 变量 | 作用 |
|---|---|
ZHISHUAI_HYIMAGE_API_KEY | API Key（不填则读 config.json） |
ZHISHUAI_HYIMAGE_MODEL | 覆盖默认模型 |
ZHISHUAI_HYIMAGE_BASE_URL | 覆盖 base_url |
首次使用：交互配置 API Key（重要）
发布版的 config.json 里 api_key 是占位符 YOUR_API_KEY_HERE，首次使用前必须配置，否则请求会返回 401。本技能支持两种配置方式，优先走「对话输入框」。
方式 A — 弹输入框卡片（agent 标准动作，推荐）：当且仅当「强制第 0 步」的 --check-key 返回 UNSET 时执行。必须用 AskUserQuestion 弹出一个带输入框的卡片（不是普通聊天提问），让用户直接在输入框里粘贴 Key：
- 调用 AskUserQuestion，参数示例：
header:配置Keyquestion: 「检测到 zhishuai-hyimage 尚未配置 API Key（首次使用）。请在下方输入框粘贴你的 www.zhishuai.net API Key（以sk-开头），我会写入本地配置并继续生成：」options（2 项）：我已在输入框填入 Key（说明：把 Key 贴在卡片底部的「其他」输入框，再选这项提交） /暂不配置，取消本次生成。
- 用户把 Key 填进输入框（走「其他」自由文本）后，agent 取到文本，先校验以
sk-开头；不符合则再次弹框要求重填，不要写入。 - 执行一次性保存命令（把 Key 写入 config.json）：
python scripts/generate_image.py --api-key <KEY> --save-key脚本会拒绝写入非法/占位符值，并以 sk- 开头校验。成功会打印「配置已保存」。
- 提示用户「配置已保存，现在可以直接生成了」，然后回到「强制第 0 步」重新
--check-key应得OK，再继续标准生成流程（同一次对话内无缝衔接）。
方式 B — 终端配置（无 agent 时）：在终端运行
python scripts/interactive.py --configure-key按提示输入 Key，自动写入 config.json。
安全提示：API Key 只写入本地 config.json，不要回显到对话、报告或日志；提醒用户妥善保管，勿外泄。
交互式生成：先让用户选参数，再提交（标准流程）
⚠️ 强制第 0 步：每次生成前，先确认 API Key 已配置
这是不可跳过的前置动作，必须在「问画面描述 / 弹选项卡片」之前完成。
用一条无副作用命令判断是否需要配置（不联网、不发请求）：
python <skill>/scripts/generate_image.py --check-key
- 退出码
0（打印KEY_STATUS=OK）→ 已配置，直接进入下面的标准流程。- 退出码
2（打印KEY_STATUS=UNSET）→ 停止，按上方「首次使用」给用户弹输入框卡片要 Key，不要直接跑生成脚本。
用户说「画 / 生成 / 做一张图」时，禁止直接提交任务。标准动作：
- 问画面描述：用户没给清楚就先问一句（自由文本）。
- 弹选项卡片让用户点选：用 AskUserQuestion 问，选项直接取自
options.json：
画面比例 → 分辨率档位 → 精确尺寸(高级) → 参考图 → 水印文字。其中：
- 画面比例必问（1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9，横竖屏都有）；
- 分辨率档位必问（1K=长边1024 / 2K=2048 / 4K=4096），与比例组合由脚本自动折算成像素；
- 精确尺寸是高级项，填了会覆盖比例+档位（脚本自动忽略后两者）；
- 参考图：用户要「基于某张图改/加内容」才问，留空=纯文生图；
- 水印文字：默认留空（不加水印），要加右下角文字才填，≤16 字符。
用户没提的项按 options.json 的 default 走，不必挨个问。（AskUserQuestion 单题上限 4 项，按需挑 4 个呈现；完整清单见 options.json 或 interactive.py --spec。）
- 复述需求 + 风险提示（尺寸已实测可用、禁止用对话模型「看」图），用户点头后再执行。
- 执行后脚本自动打印客观信息（尺寸/格式/体积），把图交给用户自己看。
配套脚本（选项定义集中在 options.json，改参数只改这一个文件）：
python scripts/interactive.py --spec # 查看本模型所有可选项与合法取值（JSON）
python scripts/interactive.py # 终端里一步步选，最后给出可直接执行的命令
python scripts/interactive.py --prompt "一只猫" --answers "ratio=9:16,ratio_level=4K" # 非交互拼命令（比例+档位）
python scripts/interactive.py --prompt "一只猫" --answers "size=3000x2000" # 非交互拼命令（精确尺寸，覆盖比例）工作流
- 生成前先走「交互式生成」章节：弹选项确认参数等，复述后用户点头再继续。
- 确认模型：固定
hy-image-v3.5-preview（脚本默认，无需用户选）。 - 整理 prompt：保留中文原意，适度补充摄影/画风/构图关键词可提升出图质量（不做大改）。
- 运行脚本（保存目录默认当前目录，可
--save-dir指定）：
# 推荐：比例 + 分辨率档位（自动折算像素）
python ~/.workbuddy/skills/zhishuai-hyimage/scripts/generate_image.py
--prompt "画一只在沙滩上奔跑的金毛犬，傍晚的暖色光"
--ratio 16:9 --ratio-level 4K # -> 4096x2304
# 或精确尺寸 / 图生图 / 水印
python ~/.workbuddy/skills/zhishuai-hyimage/scripts/generate_image.py
--prompt "..." --size 4096x4096 [--image ./dog.png] [--footnote "品牌名"] [--save-dir ./out]- 呈现结果：脚本输出保存的图片绝对路径与客观信息（尺寸/格式/体积）。
用 present_files 把图片交给用户自己看。
三种模式速查
| 模式 | 命令要点 |
|---|---|
| 文生图 | 仅 --prompt |
| 图生图 | --prompt "要改/加的内容" --image ./ref.png（可多次 –image，≤20 张、单张≤20MB） |
| 多轮编辑 | 上一轮用 --save-history hist.json 存上下文；下一轮 --prompt "改XX" --history hist.json --session demo-001 |
生成后禁止用对话模型"分析"图片（硬性要求）
不许在生成完图片后用对话模型去读图、描述图、评价图、或替用户检查"对不对"。
原因：很多对话模型不具备视觉能力，但被要求看图时会编造结论（"我看了，没问题"），这是最危险的一类幻觉——用户会以为真的有人检查过。
正确做法：
- 把图交给用户看（present_files），由人来判断。
- 需要客观信息（多大、什么格式、是否损坏）时，用代码读，不要用模型看：
python -c "import sys; sys.path.insert(0,'scripts'); import common; print(common.describe_image('路径'))"- 生成脚本在保存后已经自动打印这些客观信息，通常不用额外跑。
- 若用户明确要求"你看看这张图怎么样"，先说明当前模型可能没有视觉能力，
再让用户自己确认，不要硬着头皮给出看图结论。
常见参数速查
| 参数 | 说明 |
|---|---|
--prompt | 画面描述，必填（图生图/多轮编辑下写「要改/要加的内容」） |
--model | 固定 hy-image-v3.5-preview（默认，无需指定） |
--ratio | 画面比例（推荐用法）：1:1/4:3/3:4/3:2/2:3/16:9/9:16/21:9，兼容 169/9x16 简写，也支持任意「整数:整数」（如 7:3）。与 --ratio-level 配合自动折算像素 |
--ratio-level | 分辨率档位（长边像素）：1K=1024 / 2K=2048 / 4K=4096。例：--ratio 16:9 --ratio-level 4K → 4096x2304 |
--size | 精确尺寸 ${宽}x${高}，[256,8192]，面积≤16777216（最高 4096×4096）；给了它就忽略 –ratio |
--seed | 生成种子 int64 [0,2^63-1]，0/不传随机。⚠️ 实测不生效，不能用于复现同图（详见「全参数实测结论」） |
--generate-max-pixels | 面积档位（仅未传 size 生效）：1048576(1K)/2359296(1.5K默认)/4194304(2K)。⚠️ 实测档位无区分效果，要精确尺寸请直接用 --size |
--resize-max-pixels | 输入参考图面积上限，超出等比缩放；默认 1048576 |
--session | 会话 ID，多轮编辑保持同一值以命中 KV-cache |
--footnote | 自定义水印文字，官方限 16 字符，生成在右下角（实测超长不报错） |
--image | 图生图参考图：本地路径或 URL，可多次传入；本地自动 base64，校验格式/≤20MB/≤20 张 |
--history | 多轮编辑回灌：上一轮 assembled_history 的 JSON 文件路径 |
--save-history | 把本轮 assembled_history 存到指定 JSON，供下一轮 –history 回灌 |
--search | 开启外部搜索增强（use_search_tool） |
--save-dir | 输出目录，默认当前目录 |
--timeout | 请求超时（默认 300s） |
--raw | 打印原始 JSON 响应（排查用） |
--api-key | 临时指定 Key |
全参数实测结论（2026-09-24，22+12 个用例）
结论速览
| 参数 | 实测结果 |
|---|---|
size | ✅ 完全生效，含极端值（256×256 下限、8192×2048 面积上限 16777216 全部精确出图） |
size 越界 | ✅ 本地拦截（8192×2049 / 100×100 均在 0.5s 内报错，不发请求、不计费） |
generate_max_pixels | ⚠️ 档位无区分效果（1K/1.5K/2K 实测面积都落在 ~2.3M，见下） |
seed | ❌ 实测不生效（同 seed 三次出图完全不同，无法复现） |
footnote | ✅ 接口接受（含中文、超 16 字符不报错）；是否真渲染在图上需人眼确认 |
session | ✅ 接口接受，无报错 |
resize_max_pixels | ✅ 接口接受，无报错 |
use_search_tool | ✅ 接口接受，无报错 |
--image 图生图 | ✅ 跑通（本地图 base64 上传成功出图） |
--image 不存在 | ✅ 本地拦截报错 |
--history 多轮编辑 | ✅ 跑通（assembled_history 存 3 条消息并成功回灌生成） |
关键实测数据
1. size 强制生效（验证通过）
| 请求 size | 实际尺寸 | token | 耗时 |
|---|---|---|---|
| 不传 | 1872×1248（模型自选） | 15000 | 15.4s |
| 2560×1440 | 2560×1440 ✅ | 15000 | 21.7s |
| 1024×1024 | 1024×1024 ✅ | 15000 | 10.9s |
| 256×256（下限） | 256×256 ✅ | 15000 | 10.5s |
| 8192×2048（面积达上限 16777216） | 8192×2048 ✅ | 20000 | 48.3s |
即真·4K 及更极端的宽幅（8192 宽）都能精确出图，面积顶格时 token 从 15000 涨到 20000。
2. seed 不生效（重要）
--seed 777 连跑 3 次，三张图逐像素比对：平均像素差 70~81/255、完全一致像素 0.00% → 明显不同。
实际影响：seed 字段接口接受但不产生确定性结果，不要用于「复现同一张图」。如需风格/构图一致，改用图生图（--image）或复用同一段风格前缀 prompt。
3. generate_max_pixels 档位无区分效果
| 档位 | 实测尺寸（3 次） | 面积 |
|---|---|---|
| 1K (1048576) | 1152×2000 / 1344×1792 / 1248×1872 | ~2.35M |
| 2K (4194304) | 1248×1872 / 1248×1872 / 1280×1792 | ~2.32M |
两档实测面积几乎相同（都在 ~2.3M），远高于标称的 1K=1M / 2K=4M，且档位间无可见差异。需要精确尺寸时直接用 size 指定，不要依赖 generate_max_pixels。
4. footnote 超 16 字符不报错
官方文档规定最长 16 字符，但实测传 17 / 20 字符接口均正常返回出图，未做长度校验或报错。水印是否真的渲染在右下角、超长是否被截断，属于像素内容需人眼判断，脚本不代看。
5. 多轮编辑链路完整跑通
--save-history 存下 3 条消息（assistant+tool+assistant），--history 回灌后成功出图，F1/F2 逐像素比对平均差 42.61/255 → 背景确实被改动，编辑生效。
6. 计费实测
单次 1024×1024 / 2560×1440 均 15000 token；面积顶格（8192×2048）20000 token。22 个用例合计 275000 token、耗时 354.8s（平均约 16s/张）。
复测脚本
全参数回归脚本在本工作区：hyimage_param_test/run_params_test.py（22 用例）。改完脚本或怀疑网关变动时，重跑一遍即可拿到上表结论。
响应与保存逻辑
- 同步接口：一次请求直接返回图片，无需轮询 task。
- 最终交付图在
choices[0].delta.image.url（脚本自动下载落盘），为 12 小时临时签名 URL，务必及时下载转存。 - 判断成功依据
choices[0].delta.image.url是否存在，而非finish_reason（成功时往往为 null）。 - 内容安全拦截时返回
error.code=content_filter（HTTP 422 或 finish_reason=error），需调整 prompt。 - 图片扩展名按文件头自动识别（png/jpg/webp/gif/bmp），文件名
hyimage_<时间戳>_<序号>.ext。
多轮编辑（assembled_history 回灌）
- 响应含
assembled_history（典型 3 条：assistant+tool+assistant），是服务端拼好的下一轮回灌消息。 - 下一轮把该数组原样拼入 messages 头部，再加一条新的 user 指令即可完成「接着改」。
- 脚本支持：上一轮
--save-history hist.json存上下文；下一轮--history hist.json --session <同session>。 - 中间产物 URL（role=tool 那条）仅供回灌，不要当作最终图下载。
计费
- 按 token 计费（响应
usage.total_tokens/tokenhub_usage.total_tokens），v3.5 不拆分 prompt/completion。 - 生成失败（内容安全拦截/业务错误）不产生交付图。
网关通道状态（2026-09-24 实测，已恢复可用）
hy-image-v3.5-preview 通道已打通，可正常出图（2026-09-24 上午先后出现过「接口不存在」后恢复）。
- 上午 09:24 实测：
/v1/chat/completions报code:***.InterfaceNotExist, msg: 接口不存在（HTTP 200 业务层报错），当时通道未开。 - 上午 09:38 复测：通道已恢复，成功生成 2560×1440 图片，响应
model=HY-Image-3.5-Preview-4090-Tob-v1.1，含assembled_history（多轮编辑可用）。 - 结论：脚本与协议无 bug；若再次遇到
InterfaceNotExist，多为网关侧通道临时下线，稍后重试即可，无需改代码。
历史记录（供排查参考）：模型已注册在 /v1/models 列表；同网关 bytedance/doubao-seedream-4.0 走 /v1/images/generations、qwen-image-3.0 走 /v1/chat/completions 亦可用。
注意
- 同步接口，单次请求通常 10~60s（4K/复杂 prompt 更久），
--timeout别设太小。 - 分发/换机器时先填
config.json的api_key（或设环境变量）。 - 与
zhishuai-seedream（豆包 Seedream）分属不同协议/模型，别混用；模型名不带前缀。 - 见上方「网关通道状态」：
hy-image-v3.5-preview通道未通前，本技能会稳定报InterfaceNotExist。
