zhishu-seedream

概述

zhishuai-seedream（文生图）

调用 https://www.zhishuai.net/v1/images/generations 同步生成图片。

对接文档：本 skill 的接口形态完全对齐智谱（BigModel）对外版

【Seedream 4.0/4.5/5.0 国内接口文档】

（https://zhipu-ai.feishu.cn/wiki/A0lrwsGf4iwOS3kz3t6cFnPznLc）。

该文档的规范请求地址是 https://open.bigmodel.cn/api/v1/images/generations，

www.zhishuai.net 即这套接口的代理/中转，请求地址保持不变即可（仅 host 不同，路径 /v1/images/generations 一致）。

下文「参数结构」「响应结构」「计费」均以此文档为准。

模型名必须带 bytedance/ 前缀（网关是精确匹配）。脚本 normalize_model() 会自动为漏写前缀的模型名补 bytedance/，所以 4.0 / bytedance/doubao-seedream-4.0 两种写法都能用。

触发条件

• 用户要「画/生成/做一张图」，且上下文用的是 zhishuai 的豆包 Seedream 系列模型
• 提到模型名：doubao-seedream-4.0 / doubao-seedream-4.5 / doubao-seedream-5.0-lite（完整名 bytedance/doubao-seedream-*）

环境变量（均以 ZHISHUAI_SEEDREAM_ 为前缀，可选）

首次使用：交互配置 API Key（重要）

发布版的 config.json 里 api_key 是占位符 YOUR_API_KEY_HERE，首次使用前必须配置，否则请求会返回 401。本技能支持两种配置方式，优先走「对话输入框」。

方式 A — 弹输入框卡片（agent 标准动作，推荐）：当且仅当「强制第 0 步」的 --check-key 返回 UNSET 时执行。必须用 AskUserQuestion 弹出一个带输入框的卡片（不是普通聊天提问），让用户直接在输入框里粘贴 Key：

1. 调用 AskUserQuestion，参数示例：
   • header: 配置Key
   • question: 「检测到 zhishuai-seedream 尚未配置 API Key（首次使用）。请在下方输入框粘贴你的 www.zhishuai.net API Key（以 sk- 开头），我会写入本地配置并继续生成：」
   • options（2 项）：我已在输入框填入 Key（说明：把 Key 贴在卡片底部的「其他」输入框，再选这项提交） / 暂不配置，取消本次生成。
2. 用户把 Key 填进输入框（走「其他」自由文本）后，agent 取到文本，先校验以 sk- 开头；不符合则再次弹框要求重填，不要写入。
3. 执行一次性保存命令（把 Key 写入 config.json）：

   python scripts/generate_image.py --api-key <KEY> --save-key

脚本会拒绝写入非法/占位符值，并以 sk- 开头校验。成功会打印「配置已保存」。

1. 提示用户「配置已保存，现在可以直接生成了」，然后回到「强制第 0 步」重新 --check-key 应得 OK，再继续标准生成流程（同一次对话内无缝衔接，不用用户重复操作）。

方式 B — 终端配置（无 agent 时）：在终端运行

python scripts/interactive.py --configure-key

按提示输入 Key，自动写入 config.json。

安全提示：API Key 只写入本地 config.json，不要回显到对话、报告或日志；提醒用户妥善保管，勿外泄。

交互式生成：先让用户选比例，再提交（标准流程）

⚠️ 强制第 0 步：每次生成前，先确认 API Key 已配置

这是不可跳过的前置动作，必须在「问画面描述 / 弹选项卡片」之前完成。

用一条无副作用命令判断是否需要配置（不联网、不发请求）：

BASH复制

python <skill>/scripts/generate_image.py --check-key

• 退出码 0（打印 KEY_STATUS=OK）→ 已配置，直接进入下面的标准流程。
• 退出码 2（打印 KEY_STATUS=UNSET）→ 停止，按上方「首次使用」给用户弹输入框卡片要 Key，不要直接跑生成脚本（否则只会拿到一段报错而不是输入框）。

即使用户没提"首次使用"，只要 --check-key 返回 UNSET，就必须先要 Key 再继续；

真实 Key 已写入后，从头按标准流程走一遍即可（配置不丢，无需重复要 Key）。

用户说「画 / 生成 / 做一张图」时，禁止直接提交任务。标准动作：

1. 问画面描述：用户没给清楚就先问一句（自由文本）。
2. 弹选项卡片让用户点选：用 AskUserQuestion 问，选项直接取自 options.json：

尺寸 → 模型版本 → 张数/组图 → 水印 → 参考图。其中：

• 尺寸必问（分辨率档位 1K/2K/3K/4K，或官方推荐比例写法如 9:16）；
• 模型版本用户没提就用 options.json 的 default（4.0）；
• 张数/组图：选 1 张 = 关闭组图；选 2/4 张 = 开启自动组图并限张数；
• 水印：默认服务端加水印，可选「不加水印」；
• 参考图：用户要「基于某张图改/加内容」才问，留空=纯文生图。

用户没提的项按 options.json 的 default 走，不必挨个问。（AskUserQuestion 单题上限 4 项，按需挑 4 个呈现；完整清单见 options.json 或 interactive.py --spec。）

1. 复述需求 + 风险提示（尺寸已实测可用、禁止用对话模型「看」图），用户点头后再执行。
2. 执行后脚本自动打印客观信息（尺寸/格式/体积），把图交给用户自己看。

配套脚本（选项定义集中在 options.json，改参数只改这一个文件，不用动脚本）：

python scripts/interactive.py --spec                               # 查看本模型所有可选项与合法取值（JSON）
python scripts/interactive.py                                      # 终端里一步步选，最后给出可直接执行的命令
python scripts/interactive.py --prompt "一只猫" --answers "size=2K"   # 非交互拼命令（档位写法）
python scripts/interactive.py --prompt "一只猫" --answers "size=9:16" # 非交互拼命令（比例写法，zhishuai 扩展）

工作流

1. 生成前先走「交互式生成」章节：弹选项确认比例等，复述后用户点头再继续。
2. 确认模型：用户没说用哪个 → 默认 bytedance/doubao-seedream-4.0；用户点名 → 用点名的（自动补前缀）。

5.0-lite / 4.5 / 4.0 三个都写进 config.json 的 models，但代码不强制白名单，任何名字都透传给网关。

1. 整理 prompt：保留中文原意，适度补充摄影/画风/构图关键词可提升出图质量（不做大改）。
2. 运行脚本（保存目录默认当前目录，可 --save-dir 指定）：

   python ~/.workbuddy/skills/zhishuai-seedream/scripts/generate_image.py 
     --prompt "一只可爱的猫咪" 
     [--model doubao-seedream-4.0] [--save-dir ./out]

1. 呈现结果：脚本输出保存的图片绝对路径与客观信息（尺寸/格式/体积）。

用 present_files 把图片交给用户自己看。

生成后禁止用对话模型"分析"图片（硬性要求）

不许在生成完图片后用对话模型去读图、描述图、评价图、或替用户检查"对不对"。

原因：很多对话模型不具备视觉能力，但被要求看图时会编造结论（"我看了，没问题"），这是最危险的一类幻觉——用户会以为真的有人检查过。

正确做法：

• 把图交给用户看（present_files），由人来判断。
• 需要客观信息（多大、什么格式、是否损坏）时，用代码读，不要用模型看：

  python -c "import sys; sys.path.insert(0,'scripts'); import common; print(common.describe_image('路径'))"

输出形如 seedream_20260909_1.png | 1024x1024 | png | 1.20 MB，纯文件头解析，零幻觉。

• 生成脚本在保存后已经自动打印这些客观信息，通常不用额外跑。
• 若用户明确要求"你看看这张图怎么样"，先说明当前模型可能没有视觉能力，

再让用户自己确认，不要硬着头皮给出看图结论。

常见参数速查

图内中文文字不可靠（2026-09-10 实测，重要）

用户反馈：模型画在图里的中文标注有错字、发虚。这是模型的固有短板，提示词无法根治。

• 4K/高分辨率只能改善清晰度，错字概率依然存在。
• 真正根治：图内不出现任何文字 → 本地用 Pillow + 系统字体叠加。

可用字体：C:/Windows/Fonts/msyh.ttc（微软雅黑）、simhei.ttf（黑体）、Deng.ttf。venv C:/Users/Administrator/.workbuddy/binaries/python/envs/default 已装 Pillow + numpy。

• 用户坚持要图内文字时：把要渲染的词在 prompt 里逐词重复列出，并写明

「标准简体中文黑体印刷字，特大号，粗体，纯黑色，水平居中，笔画完整无缺笔、无重影、无变形、无多余字符、无英文、无乱码、无拼音」，可显著降低（但不能归零）出错率。

• 尺寸提示：想要 16:9 的高分辨率，用像素写法 --size 4096x2304（已实测生效），

比 --size 4K（档位，尺寸由模型决定、可能不是 16:9）更可控。

图文生图（参考图 / i2i，官方文档 3.2.2）

Seedream 支持以图生图：在请求里加 images 数组，把参考图传进去，模型据此生成。官方文档要点（已据此实现 --image）：

• 参数 images（array，图文生图时必填）：元素为图片 URL 或 data:image/<格式>;base64,<编码>。
• doubao-seedream-4.0 支持单图/多图，最多 14 张参考图；4.5 / 5.0-lite 同理支持多图。
• 参考图要求：格式 jpeg/png（4.0/4.5/5.0-lite 还接受 webp/bmp/tiff/gif）；宽高比 [1/16, 16]；

宽高 >14px；单张 ≤10MB；总像素 ≤6000×6000。

• prompt 在图文生图下用于描述想改/想加的内容（如"在画面里加一个小孩"），其余参数（size/model）同文生图。

用法（交互卡片已内置「参考图」选项，填路径即进入图文生图；也可直接调用）：

python ~/.workbuddy/skills/zhishu-seedream/scripts/generate_image.py 
  --prompt "在画面里加一个可爱的小男孩，与小猫互动，保持原光线与写实风格" 
  --image ./seedream_xxx.jpg 
  --size 4K

注意：图文生图依赖网关转发 images 字段。若返回 400 且去掉 --image 后纯文生图正常，

说明当前网关/模型暂不支持 i2i，脚本会提示改纯文生图或换模型。失败不收费。

【2026-09-10 实测】zhishuai 网关 i2i 正常可用（doubao-seedream-4.0 + 本地 jpg + --size 2560x1440），

无 400。想「锁风格换内容」时，prompt 开头固定用这句效果最好：

「严格保持参考图的画风、配色、线条、排版和中文标注样式，只更换画面主体内容：<新主题>」。

组图（sequential_image_generation，官方文档 3.2）

文档用「组图」机制产出多张关联图，不是简单的 n：

• sequential_image_generation=disabled（默认）：只出 1 张。
• sequential_image_generation=auto + sequential_image_generation_options.max_images=N：模型自动判断是否组图及数量，最多 N 张。
• 约束：参考图数量 + 最终生成张数 ≤ 15；max_images ∈ [1,15]。
• 交互卡片「张数 / 组图」：选 1 张 = 关闭组图；选 2/4 张 = 开启 auto 并限张数。
• 若网关不支持组图（返回 400），脚本会提示去掉组图参数改纯文生图或换模型。失败不收费。
• 【2026-09-10 实测】zhishuai 网关的组图是"静默降级"：传 --seq auto --max-images 4 不报错、不返回 400，

但只回 1 张（data 数组长度为 1）。因此要出 N 张图，不要依赖组图，改用 N 条 prompt 分别调用；风格一致性靠复用同一段"风格前缀"（画风/背景/构图/标注要求）来保证，实测效果稳定。

水印（watermark，官方文档 3.2）

• 默认 true：服务端在右下角加「AI生成」字样水印。
• 选「不加水印」脚本才显式发送 watermark=false。
• 默认项不发送该字段，避免多余操作。

响应与保存逻辑（以实测为准）

• 真实响应（zhishuai 直出，与文档一致）形如：

  { "created": 1788944254,
    "data": [ { "url": "https://ark-content-.../...jpeg?X-Tos-Expires=86400" } ],
    "id": "2026...", "request_id": "2026..." }

即标准 OpenAI/Zhipu 风格：图片在 data[].url。代码取 data 数组遍历，兼容 b64_json 与网关可能的 {code,message,data} 包装。

• 图片链接为火山引擎 TOS 临时地址，X-Tos-Expires=86400 ≈ 24 小时过期，务必及时下载落盘（脚本已自动下载保存）。
• 保存顺序：有 url 先下载 url；没有 url 才解码 b64_json。
• 图片扩展名按文件头自动识别（png/jpg/webp/gif/bmp），文件名 seedream_<时间戳>_<序号>.ext。

尺寸（size 参数，对接官方文档）

size 为非必填字符串，两种写法不可混用：

方式1 · 分辨率档位（原样透传，由模型据 prompt 判断具体大小）。各模型支持的档位：

4K 直接支持（4.0 / 4.5），是真 4K，无需外部方案。用错档位（如 5.0 传 4K）网关会报 400。

方式2 · 指定像素宽高（精确控制）。各模型像素范围与宽高比：

官方推荐的宽高像素值（比例别名即折算为这些，已写入脚本 RATIO_PRESETS）：

--size 透传逻辑（normalize_size）：档位 1K/2K/3K/4K 原样大写透传；WxH/比例别名折算为对应像素；非法值明确报错并列出合法写法。

• 不传 --size = 模型默认尺寸（2048×2048，仍可用）。
• 若返回 400：说明档位与当前模型不匹配（见上表），改用对应档位或像素/比例写法重试。
• 带像素尺寸时，脚本会用真实文件头比对比例（偏差 >2% 即警告"未生效"），不靠模型看图。
• 4.0 像素上限即 4096×4096，想要最大尺寸直接用 --size 4K 或 --size 4096x4096 均可。

计费（对接文档）

• 按实际生成的图片张数计费，生成失败不收费（与文档一致）。
• 单价：doubao-seedream-4.0 0.2 元/张、4.5 0.24 元/张、5.0-lite 0.22 元/张（文档公开价，以网关实际结算为准）。

注意

• 同步接口，单次请求通常 10~60s（复杂 prompt 更久），--timeout 别设太小。
• 分发/换机器时先填 config.json 的 api_key（或设环境变量）。