tuzi-image-gen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Image Generation (AI SDK)

图片生成（AI SDK）

Multi-provider image generation. Default provider: Tuzi (兔子API, api.tu-zi.com).

多供应商图片生成能力。默认供应商：Tuzi（兔子API，api.tu-zi.com）。

Script Directory

脚本目录

Agent Execution:

```
SKILL_DIR
```
= this SKILL.md file's directory
Script path =
```
${SKILL_DIR}/scripts/main.ts
```

Agent 执行规则：

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

Step 0: Load Preferences ⛔ BLOCKING

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

CRITICAL: This step MUST complete BEFORE any image generation. Do NOT skip or defer.

关键提示：本步骤必须在任何图片生成操作之前全部完成，禁止跳过或延后执行。

0.1 Check API Key

0.1 检查API密钥

Check if the selected provider's API key is available. For Tuzi (default):

bash

undefined

检查选中的供应商的API密钥是否可用。对于默认的Tuzi供应商：

bash

undefined

Check env, then .tuzi-skills/.env files

先检查环境变量，再检查 .tuzi-skills/.env 文件

echo "${TUZI_API_KEY:-not_set}" grep -s TUZI_API_KEY .tuzi-skills/.env "$HOME/.tuzi-skills/.env"


| Result | Action |
|--------|--------|
| Key found | Continue to Step 0.2 |
| Key NOT found | ⛔ Run API key setup (see [references/config/first-time-setup.md](references/config/first-time-setup.md) → "API Key Setup") → Store key → Then continue |

**CRITICAL**: If API key is missing, MUST guide user to obtain and store it BEFORE any generation. Generation is BLOCKED until key is configured.

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](references/config/first-time-setup.md) → "API Key Setup"）→ 存储密钥 → 再继续后续流程 |

**关键提示**：如果缺少API密钥，必须先引导用户获取并存储密钥，才能执行生成操作。密钥配置完成前图片生成功能处于阻塞状态。

0.2 Check EXTEND.md

0.2 检查EXTEND.md文件

Check EXTEND.md existence (priority: project → user):

bash

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

Result	Action
Found	Load, parse, apply settings. If `default_model.[provider]` is null → ask model only (Flow 2)
Not found	⛔ Run first-time setup (references/config/first-time-setup.md) → Save EXTEND.md → Then continue

CRITICAL: If not found, complete the full setup (provider + model + quality + save location) using AskUserQuestion BEFORE generating any images. Generation is BLOCKED until EXTEND.md is created.

Path	Location
`.tuzi-skills/tuzi-image-gen/EXTEND.md`	Project directory
`$HOME/.tuzi-skills/tuzi-image-gen/EXTEND.md`	User home

EXTEND.md Supports: Default provider | Default quality | Default aspect ratio | Default image size | Default models

Schema:

references/config/preferences-schema.md

检查EXTEND.md文件是否存在（优先级：项目目录 > 用户目录）：

bash

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]` 为空 → 仅询问用户选择模型（流程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支持配置项：默认供应商 | 默认画质 | 默认宽高比 | 默认图片尺寸 | 默认模型

配置规范参考：

references/config/preferences-schema.md

Usage

使用方式

bash

undefined

bash

undefined

Basic (uses Tuzi provider by default)

基础用法（默认使用Tuzi供应商）

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)

指定画质（Tuzi支持1k/2k/4k）

npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --quality 2k

4K VIP model

使用4K VIP模型

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

从prompt文件读取提示词

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

undefined

undefined

Options

可用参数

Option	Description
`--prompt <text>` , `-p`	Prompt text
`--promptfiles <files...>`	Read prompt from files (concatenated)
`--image <path>`	Output image path (required)
`--provider tuzi\|google\|openai\|dashscope\|replicate`	Force provider (default: auto-detect, Tuzi first)
`--model <id>` , `-m`	Model ID (see Tuzi Models section for full list)
`--ar <ratio>`	Aspect ratio (e.g., `16:9` , `1:1` , `4:3` ). Tuzi converts to `NxN` format
`--size <WxH>`	Size override (e.g., `1024x1024` , `16x9` )
`--quality normal\|2k`	Quality preset. Tuzi: maps to 1k/2k. Google: maps to 1K/2K
`--imageSize 1K\|2K\|4K`	Image size (Tuzi and Google). Overrides `--quality`
`--ref <files...>`	Reference images. Tuzi: base64 in JSON body. Google: multimodal. OpenAI: edits API
`--n <count>`	Number of images
`--json`	JSON output

参数	说明
`--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`
`--ref <files...>`	参考图片。Tuzi：JSON体中base64编码；Google：多模态输入；OpenAI：编辑API
`--n <count>`	生成图片数量
`--json`	输出JSON格式结果

Tuzi Models

Tuzi模型列表

Tuzi API (api.tu-zi.com) is the default provider. Models differ in quality, speed, and supported parameters.

Tuzi API（api.tu-zi.com）是默认供应商，不同模型在画质、速度和支持参数上存在差异。

Model ID	Alias	Quality	Notes
`gemini-3-pro-image-preview`	nano-banana-pro	`--quality` 1k/2k/4k	Default. High quality, supports quality param
`gemini-3.1-flash-image-preview`	nano-banana-2	`--quality` 1k/2k/4k	Fast, supports extended aspect ratios
`gemini-3-pro-image-preview-vip`	nano-banana-pro-vip	1k built-in	High quality, VIP
`gemini-3-pro-image-preview-2k-vip`	nano-banana-pro-2k-vip	2k built-in	High quality 2K, VIP
`gemini-3-pro-image-preview-4k-vip`	nano-banana-pro-4k-vip	4k built-in	High quality 4K, VIP
`gemini-2.5-flash-image-vip`	nano-banana-vip	1k built-in	Fastest, VIP

模型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专属

More Models

Model ID	Alias	Notes
`gemini-3-pro-image-preview`	nano-banana-pro	`--quality` 1k/2k/4k
`gemini-2.5-flash-image`	nano-banana	Fast
`gemini-3-pro-image-preview-hd`	nano-banana-pro-hd	HD built-in
`gemini-3-pro-image-preview-2k`	nano-banana-pro-2k	2K built-in
`gemini-3-pro-image-preview-4k`	nano-banana-pro-4k	4K built-in
`gpt-image-1.5`	—	Size: 1:1, 3:2, 2:3 only
`bfl-flux-2-pro`	flux-2-pro	Flux
`bfl-flux-2-max`	flux-2-max	Flux highest quality
`flux-kontext-pro`	kontext-pro	Multi-ref editing
`flux-kontext-max`	kontext-max	Multi-ref editing (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

模型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-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

Async Models

异步模型

Auto-detected. Script submits task and polls until complete (5s interval, max 30min).

Model ID	Notes
`gemini-3-pro-image-preview-async`	1K async
`gemini-3-pro-image-preview-2k-async`	2K async
`gemini-3-pro-image-preview-4k-async`	4K async
`mj-imagine`	Midjourney, MJ params in prompt

自动识别，脚本会提交任务后自动轮询结果（轮询间隔5秒，最长等待30分钟）。

模型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参数

Model-Specific Parameters

模型专属参数

Quality (

--quality

--imageSize 1K|2K|4K

Applies to	Values	Notes
`gemini-3.1-flash-image-preview`	1k / 2k / 4k	Default model, quality adjustable
`gemini-3-pro-image-preview`	1k / 2k / 4k	Quality adjustable
`-2k-vip` , `-4k-vip` , `*-hd`	—	Quality built into model name, param ignored
Other models	—	Param ignored

Aspect ratio (

--ar

Applies to	Supported ratios
Gemini models (default)	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`	Above + 1:4, 4:1, 1:8, 8:1 (extreme ratios)
`gpt-image-1.5`	1:1, 3:2, 2:3
Omitted	Model auto-decides

Reference images (

--ref

Sync models: base64 data URL in JSON
```
image
```
field
Async models:
```
input_reference
```
in FormData
All Tuzi models support reference images

画质（

--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-1.5`	1:1、3:2、2:3
未指定	模型自动决定

参考图片（

--ref

）：

同步模型：JSON的
```
image
```
字段传入base64格式的data URL
异步模型：FormData的
```
input_reference
```
字段传入
所有Tuzi模型均支持参考图片功能

Environment Variables

环境变量

Variable	Description
`TUZI_API_KEY`	Tuzi API key (https://api.tu-zi.com)
`TUZI_IMAGE_MODEL`	Tuzi default model (default: gemini-3-pro-image-preview)
`TUZI_BASE_URL`	Custom Tuzi endpoint (default: https://api.tu-zi.com/v1)
`GOOGLE_API_KEY`	Google API key
`OPENAI_API_KEY`	OpenAI API key
`DASHSCOPE_API_KEY`	DashScope API key (阿里云)
`REPLICATE_API_TOKEN`	Replicate API token
`GOOGLE_IMAGE_MODEL`	Google model override
`OPENAI_IMAGE_MODEL`	OpenAI model override
`DASHSCOPE_IMAGE_MODEL`	DashScope model override
`REPLICATE_IMAGE_MODEL`	Replicate model override
`GOOGLE_BASE_URL`	Custom Google endpoint
`OPENAI_BASE_URL`	Custom OpenAI endpoint
`DASHSCOPE_BASE_URL`	Custom DashScope endpoint
`REPLICATE_BASE_URL`	Custom Replicate endpoint

Load Priority: CLI args > EXTEND.md > env vars >

<cwd>/.tuzi-skills/.env

~/.tuzi-skills/.env

变量名	说明
`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模型自定义覆盖
`DASHSCOPE_IMAGE_MODEL`	DashScope模型自定义覆盖
`REPLICATE_IMAGE_MODEL`	Replicate模型自定义覆盖
`GOOGLE_BASE_URL`	自定义Google接口地址
`OPENAI_BASE_URL`	自定义OpenAI接口地址
`DASHSCOPE_BASE_URL`	自定义DashScope接口地址
`REPLICATE_BASE_URL`	自定义Replicate接口地址

加载优先级：CLI参数 > EXTEND.md配置 > 环境变量 >

<cwd>/.tuzi-skills/.env

~/.tuzi-skills/.env

Model Resolution

模型选择规则

Priority (highest → lowest), all providers:

CLI:
```
--model <id>
```
EXTEND.md:
```
default_model.[provider]
```
Env var:
```
<PROVIDER>_IMAGE_MODEL
```
Built-in default

Agent MUST display model info before each generation:

Show:
```
Using [provider] / [model]
```

Show switch hint:

Switch model: --model <id> | EXTEND.md default_model.[provider] | env <PROVIDER>_IMAGE_MODEL

所有供应商通用，优先级从高到低：

CLI参数：
```
--model <id>
```
EXTEND.md配置：
```
default_model.[provider]
```
环境变量：
```
<PROVIDER>_IMAGE_MODEL
```
内置默认值

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

展示内容：
```
Using [provider] / [model]
```

展示切换提示：

Switch model: --model <id> | EXTEND.md default_model.[provider] | env <PROVIDER>_IMAGE_MODEL

Provider Selection

供应商选择规则

```
--provider
```
specified → use it
```
--ref
```
provided + no
```
--provider
```
→ Tuzi > Google > OpenAI > Replicate
Only one API key available → use that provider
Multiple available → Tuzi first

指定了
```
--provider
```
→ 使用指定供应商
提供了
```
--ref
```
且未指定
```
--provider
```
→ 优先级Tuzi > Google > OpenAI > Replicate
仅存在一个可用API密钥 → 使用对应供应商
多个可用密钥 → 优先使用Tuzi

Quality Presets

画质预设映射

Preset	Tuzi	Google	OpenAI
`normal`	1k	1K	1024px
`2k` (default)	2k	2K	2048px

--imageSize 1K|2K|4K

overrides quality for Tuzi and Google.

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

--imageSize 1K|2K|4K

参数会覆盖Tuzi和Google的画质设置。

Generation Mode

生成模式

Default: Sequential (one at a time).

Parallel: Only when user explicitly requests. Use Task tool with

run_in_background=true

, recommended 4 subagents (max 8).

默认：串行生成（一次生成一张）

并行生成：仅当用户明确要求时启用。使用Task工具设置

run_in_background=true

，推荐最多4个子Agent（上限8个）。

Error Handling

错误处理

Missing API key → ⛔ MUST run API key setup from Step 0.1 (guide user to https://api.tu-zi.com/token, store in .tuzi-skills/.env). Do NOT suggest GOOGLE_API_KEY or other provider keys unless user explicitly chose a different provider.
Generation failure → auto-retry once
Tuzi
```
PROHIBITED_CONTENT
```
→ content rejection error
Tuzi
```
NO_IMAGE
```
→ prompt too vague, suggest more explicit prompt
Async timeout → error after 30 minutes
Invalid aspect ratio → warning, proceed with default

缺少API密钥 → ⛔ 必须执行步骤0.1的API密钥配置流程（引导用户访问https://api.tu-zi.com/token，存储到.tuzi-skills/.env）。除非用户明确选择其他供应商，否则不要推荐GOOGLE_API_KEY或其他供应商的密钥。
生成失败 → 自动重试1次
Tuzi返回
```
PROHIBITED_CONTENT
```
→ 返回内容违规错误
Tuzi返回
```
NO_IMAGE
```
→ 提示词太模糊，建议用户提供更明确的提示词
异步任务超时 → 30分钟后返回超时错误
宽高比无效 → 输出警告，使用默认比例继续执行

Replicate Models

Replicate模型使用

Format:

owner/name

owner/name:version

bash

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

格式：

owner/name

或

owner/name:version

bash

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

Extension Support

扩展支持

Custom configurations via EXTEND.md. See Step 0 for paths and supported options.

通过EXTEND.md实现自定义配置，路径和支持的配置项参考步骤0。

tuzi-image-gen

Original

Translation

Image Generation (AI SDK)

图片生成（AI SDK）

Script Directory

脚本目录

Step 0: Load Preferences ⛔ BLOCKING

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

0.1 Check API Key

0.1 检查API密钥

Check env, then .tuzi-skills/.env files

先检查环境变量，再检查 .tuzi-skills/.env 文件

0.2 Check EXTEND.md

0.2 检查EXTEND.md文件

Usage

使用方式

Basic (uses Tuzi provider by default)

基础用法（默认使用Tuzi供应商）

With aspect ratio

指定宽高比

With quality (Tuzi: 1k/2k/4k)

指定画质（Tuzi支持1k/2k/4k）

4K VIP model

使用4K VIP模型

With reference images

使用参考图

From prompt files

从prompt文件读取提示词

Async model (auto-polls)

异步模型（自动轮询结果）

Other providers

使用其他供应商

Options

可用参数

Tuzi Models

Tuzi模型列表

Recommended

推荐模型

More Models

更多模型

Async Models

异步模型

Model-Specific Parameters

模型专属参数

Environment Variables

环境变量

Model Resolution

模型选择规则

Provider Selection

供应商选择规则

Quality Presets

画质预设映射

Generation Mode

生成模式

Error Handling

错误处理

Replicate Models

Replicate模型使用

Extension Support

扩展支持