tuzi-image-gen

图像生成（AI SDK）

支持多提供方的图像生成。默认提供方：Tuzi（兔子API，api.tu-zi.com）。

脚本目录

Agent 执行：

1. SKILL_DIR = 此 SKILL.md 文件所在目录
2. 脚本路径 = ${SKILL_DIR}/scripts/main.ts

步骤 0：加载偏好设置 ⛔ 阻塞

重要：此步骤必须在任何图像生成之前完成。不得跳过或延后。

0.1 检查 API 密钥

检查所选提供方的 API 密钥是否可用。对于 Tuzi（默认）：

# Check env, then .tuzi-skills/.env files
echo "${TUZI_API_KEY:-not_set}"
grep -s TUZI_API_KEY .tuzi-skills/.env "$HOME/.tuzi-skills/.env"

结果	操作
找到密钥	继续步骤 0.2
未找到密钥	⛔ 运行 API 密钥设置（参见 references/config/first-time-setup.md →“API 密钥设置”）→ 保存密钥 → 然后继续

重要：如果缺少 API 密钥，必须先引导用户获取并保存密钥，然后才能进行任何生成。配置好密钥之前，生成操作会被阻止。

0.2 检查 EXTEND.md

检查 EXTEND.md 是否存在（优先级：项目 → 用户）：

test -f .tuzi-skills/tuzi-image-gen/EXTEND.md && echo "project"
test -f "$HOME/.tuzi-skills/tuzi-image-gen/EXTEND.md" && echo "user"

结果	操作
已找到	加载、解析并应用设置。如果 default_model.[provider] 为 null → 仅询问模型（流程 2）
未找到	⛔ 运行首次设置（references/config/first-time-setup.md）→ 保存 EXTEND.md → 然后继续

重要：如果未找到，必须使用 AskUserQuestion 完成完整设置（提供方 + 模型 + 质量 + 保存位置），然后才能生成任何图像。创建 EXTEND.md 之前，生成操作会被阻止。

路径	位置
.tuzi-skills/tuzi-image-gen/EXTEND.md	项目目录
$HOME/.tuzi-skills/tuzi-image-gen/EXTEND.md	用户主目录

EXTEND.md 支持：默认提供方 | 默认质量 | 默认宽高比 | 默认图像尺寸 | OpenAI 图像 API 方言 | 默认模型

架构：references/config/preferences-schema.md

用法

# Basic (uses Tuzi provider by default)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image cat.png

# With aspect ratio
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A landscape" --image out.png --ar 16:9

# With quality (Tuzi: 1k/2k/4k)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --quality 2k

# 4K VIP model
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --model gemini-3-pro-image-preview-4k-vip

# With reference images
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Make it blue" --image out.png --ref source.png

# From prompt files
npx -y bun ${SKILL_DIR}/scripts/main.ts --promptfiles system.md content.md --image out.png

# Async model (auto-polls)
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --model gemini-3-pro-image-preview-2k-async

# Other providers
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider google
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider openai
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只可爱的猫" --image out.png --provider dashscope
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate

# OpenAI-compatible gateway dialect
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider openai --imageApiDialect ratio-metadata

选项

选项	描述
--prompt <text>，-p	提示词文本
--promptfiles <files...>	从文件读取提示词（拼接）
--image <path>	输出图像路径（必需）
--provider tuzi|google|openai|dashscope|replicate	强制指定提供方（默认：自动检测，优先 Tuzi）
--model <id>，-m	模型 ID（完整列表见 Tuzi 模型部分）
--ar <ratio>	宽高比（例如，16:9、1:1、4:3）。Tuzi 会转换为 NxN 格式
--size <WxH>	覆盖尺寸（例如，1024x1024、16x9）
--quality normal|2k	质量预设。Tuzi：映射到 1k/2k。Google：映射到 1K/2K
--imageSize 1K|2K|4K	图像尺寸（Tuzi 和 Google）。覆盖 --quality
--imageApiDialect openai-native|ratio-metadata	OpenAI 兼容端点方言。ratio-metadata 适用于要求使用宽高比 size 加上 metadata.resolution 的网关
--ref <files...>	参考图像。Tuzi：在 JSON 请求体中使用 base64。Google：多模态。OpenAI：编辑 API
--n <count>	图像数量
--json	JSON 输出

Tuzi 模型

Tuzi API（api.tu-zi.com）是默认提供方。模型在质量、速度和支持的参数方面各不相同。

推荐

模型 ID	别名	质量	备注
gemini-3-pro-image-preview	nano-banana-pro	--quality 1k/2k/4k	默认。质量高，支持质量参数
gemini-3.1-flash-image-preview	nano-banana-2	--quality 1k/2k/4k	速度快，支持扩展宽高比
gemini-3-pro-image-preview-vip	nano-banana-pro-vip	内置 1k	质量高，VIP
gemini-3-pro-image-preview-2k-vip	nano-banana-pro-2k-vip	内置 2k	高质量 2K，VIP
gemini-3-pro-image-preview-4k-vip	nano-banana-pro-4k-vip	内置 4k	高质量 4K，VIP
gemini-2.5-flash-image-vip	nano-banana-vip	内置 1k	速度最快，VIP

更多模型

模型 ID	别名	说明
gemini-3-pro-image-preview	nano-banana-pro	--quality 1k/2k/4k
gemini-2.5-flash-image	nano-banana	快速
gemini-3-pro-image-preview-hd	nano-banana-pro-hd	内置 HD
gemini-3-pro-image-preview-2k	nano-banana-pro-2k	内置 2K
gemini-3-pro-image-preview-4k	nano-banana-pro-4k	内置 4K
gpt-image-2	—	OpenAI 最新图像模型，支持现代尺寸规则
gpt-image-1.5	—	尺寸：仅支持 1:1、3:2、2:3
bfl-flux-2-pro	flux-2-pro	Flux
bfl-flux-2-max	flux-2-max	Flux，最高画质
flux-kontext-pro	kontext-pro	多参考图编辑
flux-kontext-max	kontext-max	多参考图编辑（最高级）
doubao-seedream-4-0-250828	Seedream 4.0	2K/4K
doubao-seedream-4-5-251128	Seedream 4.5	2K/4K
doubao-seedream-5-0-260128	Seedream 5.0 lite	2K/3K

异步模型

自动检测。脚本提交任务并轮询直至完成（间隔 5s，最长 30min）。

模型 ID	说明
gemini-3-pro-image-preview-async	1K 异步
gemini-3-pro-image-preview-2k-async	2K 异步
gemini-3-pro-image-preview-4k-async	4K 异步
mj-imagine	Midjourney，提示词中包含 MJ 参数

特定模型参数

画质（--quality 或 --imageSize 1K|2K|4K）：

适用范围	值	说明
gemini-3.1-flash-image-preview	1k / 2k / 4k	默认模型，可调整画质
gemini-3-pro-image-preview	1k / 2k / 4k	可调整画质
*-2k-vip、*-4k-vip、*-hd	—	画质已内置于模型名称中，忽略此参数
其他模型	—	忽略此参数

宽高比（--ar）：

适用范围	支持的比例
Gemini 模型（默认）	1:1、16:9、9:16、3:2、2:3、4:3、3:4、5:4、4:5、21:9
gemini-3.1-flash-image-preview	上述比例 + 1:4、4:1、1:8、8:1（极端比例）
gpt-image-2	通过生成有效像素尺寸支持灵活比例；自定义 --size 必须符合 OpenAI 限制
gpt-image-1.5	1:1、3:2、2:3
doubao-seedream-*	使用显式的 --size / --imageSize；不支持单独使用 --ar
未指定	由模型自动决定

参考图（--ref）：

• gpt-image-*：使用 OpenAI 风格的 /images/edits 多部分上传
• 其他同步模型：在 JSON 的 image 字段中使用 base64 数据 URL
• 异步模型：在 FormData 中使用 input_reference
• 大多数 Tuzi 同步模型支持参考图；doubao-seedream-3-0-* 不支持

Seedream（doubao-seedream-*）：

适用范围	尺寸规则	参考图
doubao-seedream-5-0-*	2K、3K 或显式的 WxH	最多 14 张
doubao-seedream-4-5-*	2K、4K 或显式的 WxH	最多 14 张
doubao-seedream-4-0-*	1K、2K、4K 或显式的 WxH	最多 14 张
doubao-seedream-3-0-*	仅支持显式的 WxH	不支持

环境变量

变量	说明
TUZI_API_KEY	Tuzi API 密钥（https://api.tu-zi.com）
TUZI_IMAGE_MODEL	Tuzi 默认模型（默认值：gemini-3-pro-image-preview）
TUZI_BASE_URL	自定义 Tuzi 端点（默认值：https://api.tu-zi.com/v1）
GOOGLE_API_KEY	Google API 密钥
OPENAI_API_KEY	OpenAI API 密钥
DASHSCOPE_API_KEY	DashScope API 密钥（阿里云）
REPLICATE_API_TOKEN	Replicate API 令牌
GOOGLE_IMAGE_MODEL	Google 模型覆盖值
OPENAI_IMAGE_MODEL	OpenAI 模型覆盖值（默认值：gpt-image-2）
DASHSCOPE_IMAGE_MODEL	DashScope 模型覆盖值
REPLICATE_IMAGE_MODEL	Replicate 模型覆盖值
GOOGLE_BASE_URL	自定义 Google 端点
OPENAI_BASE_URL	自定义 OpenAI 端点
OPENAI_IMAGE_API_DIALECT	OpenAI 兼容端点方言（openai-native 或 ratio-metadata）
DASHSCOPE_BASE_URL	自定义 DashScope 端点
REPLICATE_BASE_URL	自定义 Replicate 端点

加载优先级：CLI 参数 > EXTEND.md > 环境变量 > <cwd>/.tuzi-skills/.env > ~/.tuzi-skills/.env

模型解析

优先级（从高到低），适用于所有提供商：

1. CLI：--model <id>
2. EXTEND.md：default_model.[provider]
3. 环境变量：<PROVIDER>_IMAGE_MODEL
4. 内置默认值

Agent 必须在每次生成前显示模型信息：

• 显示：Using [provider] / [model]
• 显示切换提示：Switch model: --model <id> | EXTEND.md default_model.[provider] | env <PROVIDER>_IMAGE_MODEL

提供商选择

1. 指定了 --provider → 使用该提供商
2. 提供了 --ref 且未指定 --provider → Tuzi > Google > OpenAI > Replicate
3. 只有一个可用的 API 密钥 → 使用对应提供商
4. 有多个可用密钥 → 优先使用 Tuzi

OpenAI 兼容方言

当 provider=openai 时，端点可能仍是 OpenAI 兼容网关，而非原生 OpenAI 基础设施。

• openai-native：标准 OpenAI Images API 请求正文
• ratio-metadata：发送宽高比 size 和 metadata.resolution，适用于连接非原生图像后端的兼容网关

当前限制：ratio-metadata 仅支持文生图。使用 --ref 时，请使用 openai-native。

质量预设

预设	Tuzi	Google	OpenAI
normal	1k	1K	1024px
2k（默认）	2k	2K	2048px

--imageSize 1K|2K|4K 可覆盖 Tuzi 和 Google 的质量设置。

生成模式

默认：依次生成（一次一个）。

并行：仅在用户明确要求时使用。使用 Task 工具并设置 run_in_background=true，建议使用 4 个子 Agent（最多 8 个）。

错误处理

• 缺少 API 密钥 → ⛔ 必须执行第 0.1 步中的 API 密钥设置（引导用户前往 https://api.tu-zi.com/token，并将密钥存储在 .tuzi-skills/.env 中）。除非用户明确选择了其他提供商，否则不要建议使用 GOOGLE_API_KEY 或其他提供商的密钥。
• 生成失败 → 自动重试一次
• Tuzi PROHIBITED_CONTENT → 内容被拒绝错误
• Tuzi NO_IMAGE → 提示词过于模糊，建议使用更明确的提示词
• 异步超时 → 30 分钟后报错
• 宽高比无效 → 发出警告，并使用默认值继续

Replicate 模型

格式：owner/name 或 owner/name:version

npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate --model google/nano-banana-2 --ar 16:9
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A fashion photo" --image out.png --provider replicate --model bytedance/seedream-4.5 --size 4K
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cinematic scene" --image out.png --provider replicate --model wan-video/wan-2.7-image-pro --size 4K

支持的系列

系列	示例模型	参考图像	宽高比	尺寸处理	备注
Nano Banana	google/nano-banana、google/nano-banana-pro、google/nano-banana-2	最多 14 张	文档中列出的标准宽高比	--quality 映射到 1K/2K，--size 可推断宽高比和 1K/2K	默认兼容性最佳
Seedream 4.5	bytedance/seedream-4.5	最多 14 张	文档中列出的标准宽高比	--size 支持 2K、4K 或自定义 WxH	适合生成高分辨率输出
Seedream 5 Lite	bytedance/seedream-5-lite	最多 14 张	文档中列出的标准宽高比	--size 支持 2K 或 3K	尺寸预设更简单
Wan 2.7 Image	wan-video/wan-2.7-image	最多 9 张	W:H 宽高比会转换为尺寸	--size 支持 1K、2K 或自定义 WxH	参考图像使用 images 字段
Wan 2.7 Image Pro	wan-video/wan-2.7-image-pro	最多 9 张	W:H 宽高比会转换为尺寸	--size 支持 1K、2K、4K 或自定义 WxH	4K 仅适用于文生图（不带 --ref）

Replicate 说明

• 当前工具每次请求只保存一张图像，因此 Replicate 仅支持 --n 1。
• Replicate 不使用 --imageSize。请改用 --quality、--ar 或 --size。
• 未知的 Replicate 模型仍可用于仅根据提示词生成内容，但只有上述系列可以保证支持 --ref、--ar 和 --size。
• 此工具中 Nano Banana 和 Seedream 共用的文档所列宽高比：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9。

扩展支持

通过 EXTEND.md 使用自定义配置。路径和支持的选项请参见 步骤 0。