Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
tuziapi avatar

Tuzi Image Gen

  • 199 installs
  • 37 repo stars
  • Updated April 24, 2026
  • tuziapi/tuzi-skills

Use tuzi-image-gen for development tasks

About

tuzi-image-gen: A skill skill for development. This skill provides functionality for development workflows.

  • tuzi-image-gen

Tuzi Image Gen by the numbers

  • 199 all-time installs (skills.sh)
  • Ranked #2,040 of 4,347 Backend & APIs skills by installs in the Skillselion catalog
  • Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/tuziapi/tuzi-skills --skill tuzi-image-gen

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs199
repo stars37
Last updatedApril 24, 2026
Repositorytuziapi/tuzi-skills

What it does

Use tuzi-image-gen for development tasks

Files

SKILL.mdMarkdownGitHub ↗

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"
ResultAction
Key foundContinue to Step 0.2
Key NOT found⛔ Run API key setup (see 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.

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"
ResultAction
FoundLoad, 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.

PathLocation
.tuzi-skills/tuzi-image-gen/EXTEND.mdProject directory
$HOME/.tuzi-skills/tuzi-image-gen/EXTEND.mdUser home

EXTEND.md Supports: Default provider | Default quality | Default aspect ratio | Default image size | OpenAI image API dialect | 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

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

Options

OptionDescription
--prompt <text>, -pPrompt text
--promptfiles <files...>Read prompt from files (concatenated)
--image <path>Output image path (required)
`--provider tuzi\google\
--model <id>, -mModel 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`
`--imageSize 1K\2K\
`--imageApiDialect openai-native\ratio-metadata`
--ref <files...>Reference images. Tuzi: base64 in JSON body. Google: multimodal. OpenAI: edits API
--n <count>Number of images
--jsonJSON output

Tuzi Models

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

Recommended

Model IDAliasQualityNotes
gemini-3-pro-image-previewnano-banana-pro--quality 1k/2k/4kDefault. High quality, supports quality param
gemini-3.1-flash-image-previewnano-banana-2--quality 1k/2k/4kFast, supports extended aspect ratios
gemini-3-pro-image-preview-vipnano-banana-pro-vip1k built-inHigh quality, VIP
gemini-3-pro-image-preview-2k-vipnano-banana-pro-2k-vip2k built-inHigh quality 2K, VIP
gemini-3-pro-image-preview-4k-vipnano-banana-pro-4k-vip4k built-inHigh quality 4K, VIP
gemini-2.5-flash-image-vipnano-banana-vip1k built-inFastest, VIP

More Models

Model IDAliasNotes
gemini-3-pro-image-previewnano-banana-pro--quality 1k/2k/4k
gemini-2.5-flash-imagenano-bananaFast
gemini-3-pro-image-preview-hdnano-banana-pro-hdHD built-in
gemini-3-pro-image-preview-2knano-banana-pro-2k2K built-in
gemini-3-pro-image-preview-4knano-banana-pro-4k4K built-in
gpt-image-2OpenAI latest image model, supports modern size rules
gpt-image-1.5Size: 1:1, 3:2, 2:3 only
bfl-flux-2-proflux-2-proFlux
bfl-flux-2-maxflux-2-maxFlux highest quality
flux-kontext-prokontext-proMulti-ref editing
flux-kontext-maxkontext-maxMulti-ref editing (max)
doubao-seedream-4-0-250828Seedream 4.02K/4K
doubao-seedream-4-5-251128Seedream 4.52K/4K
doubao-seedream-5-0-260128Seedream 5.0 lite2K/3K

Async Models

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

Model IDNotes
gemini-3-pro-image-preview-async1K async
gemini-3-pro-image-preview-2k-async2K async
gemini-3-pro-image-preview-4k-async4K async
mj-imagineMidjourney, MJ params in prompt

Model-Specific Parameters

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

Applies toValuesNotes
gemini-3.1-flash-image-preview1k / 2k / 4kDefault model, quality adjustable
gemini-3-pro-image-preview1k / 2k / 4kQuality adjustable
*-2k-vip, *-4k-vip, *-hdQuality built into model name, param ignored
Other modelsParam ignored

Aspect ratio (--ar):

Applies toSupported 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-previewAbove + 1:4, 4:1, 1:8, 8:1 (extreme ratios)
gpt-image-2Flexible ratio via generated valid pixel size; custom --size must satisfy OpenAI constraints
gpt-image-1.51:1, 3:2, 2:3
doubao-seedream-*Use explicit --size / --imageSize; --ar alone is not supported
OmittedModel auto-decides

Reference images (--ref):

  • gpt-image-*: OpenAI-style /images/edits multipart upload
  • Other sync models: base64 data URL in JSON image field
  • Async models: input_reference in FormData
  • Most Tuzi sync models support reference images; doubao-seedream-3-0-* does not

Seedream (doubao-seedream-*):

Applies toSize rulesReference images
doubao-seedream-5-0-*2K, 3K, or explicit WxHUp to 14
doubao-seedream-4-5-*2K, 4K, or explicit WxHUp to 14
doubao-seedream-4-0-*1K, 2K, 4K, or explicit WxHUp to 14
doubao-seedream-3-0-*Explicit WxH onlyNot supported

Environment Variables

VariableDescription
TUZI_API_KEYTuzi API key (https://api.tu-zi.com)
TUZI_IMAGE_MODELTuzi default model (default: gemini-3-pro-image-preview)
TUZI_BASE_URLCustom Tuzi endpoint (default: https://api.tu-zi.com/v1)
GOOGLE_API_KEYGoogle API key
OPENAI_API_KEYOpenAI API key
DASHSCOPE_API_KEYDashScope API key (阿里云)
REPLICATE_API_TOKENReplicate API token
GOOGLE_IMAGE_MODELGoogle model override
OPENAI_IMAGE_MODELOpenAI model override (default: gpt-image-2)
DASHSCOPE_IMAGE_MODELDashScope model override
REPLICATE_IMAGE_MODELReplicate model override
GOOGLE_BASE_URLCustom Google endpoint
OPENAI_BASE_URLCustom OpenAI endpoint
OPENAI_IMAGE_API_DIALECTOpenAI-compatible endpoint dialect (openai-native or ratio-metadata)
DASHSCOPE_BASE_URLCustom DashScope endpoint
REPLICATE_BASE_URLCustom Replicate endpoint

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

OpenAI-Compatible Dialect

When provider=openai, the endpoint may still be an OpenAI-compatible gateway rather than native OpenAI infrastructure.

  • openai-native: standard OpenAI Images API request body
  • ratio-metadata: sends aspect-ratio size plus metadata.resolution, useful for compatibility gateways in front of non-native image backends

Current limitation: ratio-metadata is text-to-image only. When using --ref, stay on openai-native.

Quality Presets

PresetTuziGoogleOpenAI
normal1k1K1024px
2k (default)2k2K2048px

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

Supported Families

FamilyExample modelsReference imagesAspect ratioSize handlingNotes
Nano Bananagoogle/nano-banana, google/nano-banana-pro, google/nano-banana-2Up to 14Standard documented ratios--quality maps to 1K/2K, --size can infer ratio + 1K/2KBest default compatibility
Seedream 4.5bytedance/seedream-4.5Up to 14Standard documented ratios--size supports 2K, 4K, or custom WxHGood for high-resolution output
Seedream 5 Litebytedance/seedream-5-liteUp to 14Standard documented ratios--size supports 2K or 3KSimpler size presets
Wan 2.7 Imagewan-video/wan-2.7-imageUp to 9W:H ratios converted into size--size supports 1K, 2K, or custom WxHReference images use images field
Wan 2.7 Image Prowan-video/wan-2.7-image-proUp to 9W:H ratios converted into size--size supports 1K, 2K, 4K, or custom WxH4K only for text-to-image (no --ref)

Replicate Notes

  • Current tool saves exactly one image per request, so Replicate supports --n 1 only.
  • --imageSize is not used for Replicate. Use --quality, --ar, or --size instead.
  • Unknown Replicate models still work for prompt-only generation, but --ref, --ar, and --size are only guaranteed for the families listed above.
  • Documented aspect ratios shared by Nano Banana and Seedream in this tool: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.

Extension Support

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

Related skills

Backend & APIsbackendintegrations

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.