Image Generation (AI SDK)

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

Script Directory

Agent Execution:

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

Step 0: Load Preferences ⛔ BLOCKING

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

0.1 Check API Key

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

# 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"

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

0.2 Check EXTEND.md

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

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

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.

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

Schema: references/config/preferences-schema.md

Usage

# 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

Options

Tuzi Models

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

Recommended

More Models

Async Models

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

Model-Specific Parameters

Quality (--quality or --imageSize 1K|2K|4K):

Aspect ratio (--ar):

Reference images (--ref):

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

Environment Variables

Load Priority: CLI args > EXTEND.md > env vars > <cwd>/.tuzi-skills/.env > ~/.tuzi-skills/.env

Model Resolution

Priority (highest → lowest), all providers:

1. CLI: --model <id>
2. EXTEND.md: default_model.[provider]
3. Env var: <PROVIDER>_IMAGE_MODEL
4. 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

Provider Selection

1. --provider specified → use it
2. --ref provided + no --provider → Tuzi > Google > OpenAI > Replicate
3. Only one API key available → use that provider
4. Multiple available → Tuzi first

Quality Presets

--imageSize 1K|2K|4K overrides quality for Tuzi and 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).

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

Replicate Models

Format: owner/name or 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

Extension Support

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