minimax-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MiniMax Image 文生图技能

MiniMax Image Text-to-Image Skill

使用 MiniMax Image01 API 进行高质量的文生图和图生图创作，支持多种宽高比和批量生成。

CRITICAL: 所有脚本路径使用

${CLAUDE_SKILL_DIR}

变量引用，确保插件安装后无论用户工作目录在哪都能正确找到脚本。

Create high-quality text-to-image and image-to-image content using the MiniMax Image01 API, supporting multiple aspect ratios and batch generation.

CRITICAL: All script paths use the

${CLAUDE_SKILL_DIR}

variable reference to ensure that the scripts can be found correctly regardless of the user's working directory after plugin installation.

Quick Reference

任务	命令
生成单张图片	`bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "prompt"`
指定宽高比	`bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "prompt" --aspect-ratio 16:9`
批量生成	`bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "prompt" -n 4`
指定输出目录	`bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "prompt" --output-dir ./images`
自定义文件名前缀	`bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "prompt" --prefix my_photo`
图生图（主体一致性）	`bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "prompt" --reference-image <URL>`

Task	Command
Generate a single image	`bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "prompt"`
Specify aspect ratio	`bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "prompt" --aspect-ratio 16:9`
Batch generation	`bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "prompt" -n 4`
Specify output directory	`bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "prompt" --output-dir ./images`
Custom filename prefix	`bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "prompt" --prefix my_photo`
Image-to-image (subject consistency)	`bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "prompt" --reference-image <URL>`

前置要求

Prerequisites

必需环境变量：

bash

export MINIMAX_API_KEY="your_api_key_here"

可选环境变量：

bash

undefined

Required environment variables:

bash

export MINIMAX_API_KEY="your_api_key_here"

Optional environment variables:

bash

undefined

API 主机地址（国内站默认 https://api.minimaxi.com）

API host address (default for domestic sites is https://api.minimaxi.com)

export MINIMAX_API_HOST="https://api.minimaxi.com"

undefined

export MINIMAX_API_HOST="https://api.minimaxi.com"

undefined

使用方式

Usage

文生图

Text-to-Image

bash

undefined

bash

undefined

基本用法 - 生成 1:1 正方形图片

Basic usage - generate 1:1 square image

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "a cute fluffy cat sitting on a windowsill"

指定宽高比（16:9 宽屏适合桌面壁纸）

Specify aspect ratio (16:9 widescreen suitable for desktop wallpapers)

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "girl in a library" --aspect-ratio 16:9

竖屏比例（9:16 适合手机壁纸）

Vertical ratio (9:16 suitable for mobile wallpapers)

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "futuristic city skyline" --aspect-ratio 9:16

批量生成 4 张图片，指定输出目录

Batch generate 4 images, specify output directory

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "dreamy forest" -n 4 --output-dir ./outputs

自定义文件名前缀

Custom filename prefix

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "abstract art" --prefix abstract_1

undefined

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "abstract art" --prefix abstract_1

undefined

图生图（保持主体一致性）

Image-to-Image (Maintain Subject Consistency)

提供一张参考图，生成保持人物/物体特征一致的新图片。

bash

undefined

Provide a reference image to generate new images that retain the features of the person/object.

bash

undefined

使用参考图 URL，生成保持角色一致的新图片

Use reference image URL to generate new images with consistent character

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts
"girl reading by the window, sunlight"
--reference-image "https://example.com/reference_face.jpg"


**CRITICAL**: 参考图必须是单人正面清晰照片，模型才能更好地理解人像信息。支持公网 URL 或 base64 格式。

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts
"girl reading by the window, sunlight"
--reference-image "https://example.com/reference_face.jpg"


**CRITICAL**: The reference image must be a clear front-facing photo of a single person for the model to better understand portrait information. Public URLs or base64 format are supported.

API 参数说明

API Parameter Description

参数	类型	默认值	说明
`prompt`	string	必填	图片描述文本，最长 1500 字符，英文描述效果更好
`model`	string	`image-01`	模型名称
`aspect_ratio`	string	`1:1`	宽高比，见下方支持列表
`response_format`	string	`base64`	返回格式： `base64` 或 `url` （url 有效期 24 小时）
`n`	int	`1`	生成数量，1-9 张
`output_dir`	string	`.`	图片保存目录
`prefix`	string	`image_{timestamp}`	输出文件名前缀
`subject_reference`	object	无	图生图主体参考（见下方）

Parameter	Type	Default Value	Description
`prompt`	string	Required	Image description text, maximum 1500 characters, English descriptions yield better results
`model`	string	`image-01`	Model name
`aspect_ratio`	string	`1:1`	Aspect ratio, see supported list below
`response_format`	string	`base64`	Return format: `base64` or `url` (url is valid for 24 hours)
`n`	int	`1`	Number of images to generate, 1-9
`output_dir`	string	`.`	Image save directory
`prefix`	string	`image_{timestamp}`	Output filename prefix
`subject_reference`	object	None	Subject reference for image-to-image (see below)

CLI 参数

CLI Parameters

参数	缩写	说明
`--aspect-ratio`	`-r`	宽高比
`--output-dir`	`-o`	输出目录
`--format`	`-f`	返回格式：base64 / url
`--n`	`-n`	生成数量 1-9
`--prefix`	`-p`	文件名前缀
`--reference-image`	`-i`	参考图 URL（图生图）
`--help`	`-h`	显示帮助信息

Parameter	Abbreviation	Description
`--aspect-ratio`	`-r`	Aspect ratio
`--output-dir`	`-o`	Output directory
`--format`	`-f`	Return format: base64 / url
`--n`	`-n`	Number of images to generate (1-9)
`--prefix`	`-p`	Filename prefix
`--reference-image`	`-i`	Reference image URL (image-to-image)
`--help`	`-h`	Display help information

支持的宽高比

Supported Aspect Ratios

比例	分辨率	适用场景
`1:1`	1024x1024	正方形，社交媒体头像
`16:9`	1280x720	宽屏，桌面壁纸、视频封面
`9:16`	720x1280	竖屏，手机壁纸、短视频封面
`4:3`	1152x864	标准屏幕，PPT 配图
`3:4`	864x1152	竖版标准，海报
`3:2`	1248x832	摄影比例，风景照片风格
`2:3`	832x1248	竖版摄影，人像照片风格
`21:9`	1344x576	超宽屏，电影感画面（仅 image-01）

Ratio	Resolution	Application Scenario
`1:1`	1024x1024	Square, social media avatars
`16:9`	1280x720	Widescreen, desktop wallpapers, video covers
`9:16`	720x1280	Vertical screen, mobile wallpapers, short video covers
`4:3`	1152x864	Standard screen, PPT illustrations
`3:4`	864x1152	Vertical standard, posters
`3:2`	1248x832	Photography ratio, landscape photo style
`2:3`	832x1248	Vertical photography, portrait photo style
`21:9`	1344x576	Ultra-widescreen, cinematic scenes (image-01 only)

subject_reference 参数说明

subject_reference Parameter Description

字段	类型	说明
`type`	string	主体类型，目前仅支持 `character` （人物）
`image_file`	string	参考图片，支持公网 URL 或 `data:image/jpeg;base64,{data}` 格式

Field	Type	Description
`type`	string	Subject type, currently only supports `character` (person)
`image_file`	string	Reference image, supports public URL or `data:image/jpeg;base64,{data}` format

❌ WRONG / ✅ CORRECT

❌ WRONG - 中文提示词效果差

❌ WRONG - Chinese prompts yield poor results

bash

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "一个可爱的猫咪坐在窗台上"

bash

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "一个可爱的猫咪坐在窗台上"

✅ CORRECT - 英文提示词效果更好

✅ CORRECT - English prompts yield better results

bash

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "a cute fluffy cat sitting on a windowsill, sunlight, warm colors"

bash

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "a cute fluffy cat sitting on a windowsill, sunlight, warm colors"

❌ WRONG - 参考图不是正面清晰照片

❌ WRONG - Reference image is not a clear front-facing photo

bash

undefined

bash

undefined

侧脸、模糊、多人照片，模型难以提取特征

Side profile, blurry, or group photos make it difficult for the model to extract features

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "girl reading" -i "https://example.com/group_photo.jpg"

undefined

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "girl reading" -i "https://example.com/group_photo.jpg"

undefined

✅ CORRECT - 使用单人正面清晰照片

✅ CORRECT - Use a clear front-facing photo of a single person

bash

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "girl reading" -i "https://example.com/clear_frontal_face.jpg"

bash

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "girl reading" -i "https://example.com/clear_frontal_face.jpg"

❌ WRONG - 忘记指定输出目录，图片散落在当前目录

❌ WRONG - Forgetting to specify output directory, images scattered in current directory

bash

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "a cute cat" -n 4

bash

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "a cute cat" -n 4

✅ CORRECT - 指定输出目录和文件名前缀

✅ CORRECT - Specify output directory and filename prefix

bash

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "a cute cat" -n 4 --output-dir ./images --prefix cat

bash

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "a cute cat" -n 4 --output-dir ./images --prefix cat

错误处理

Error Handling

错误信息	原因	解决方案
`MINIMAX_API_KEY environment variable is not set`	未设置环境变量	`export MINIMAX_API_KEY="xxx"`
`HTTP 错误: 401`	API Key 无效	检查 Key 是否正确
`HTTP 错误: 429`	请求过于频繁	降低请求频率，或检查配额
`API 错误: ...`	API 返回错误	检查错误信息，常见原因：prompt 过长、参数不合法
`生成数量必须在 1-9 之间`	n 参数超出范围	使用 1-9 之间的值

Error Message	Cause	Solution
`MINIMAX_API_KEY environment variable is not set`	Environment variable not set	`export MINIMAX_API_KEY="xxx"`
`HTTP Error: 401`	Invalid API Key	Check if the Key is correct
`HTTP Error: 429`	Too many requests	Reduce request frequency, or check quota
`API Error: ...`	API returned error	Check error message, common causes: prompt too long, invalid parameters
`Number of generated images must be between 1-9`	n parameter out of range	Use a value between 1-9

脚本帮助

Script Help

bash

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts -- --help

bash

bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts -- --help

最佳实践

Best Practices

CRITICAL: 英文提示词效果远好于中文，务必使用英文描述
批量生成前检查配额：使用
```
minimax-usage
```
skill 先检查余额
提示词优化：详细描述场景、光线、风格，效果更好
指定输出目录：使用
```
--output-dir
```
避免图片散落在当前目录
自定义文件名前缀：使用
```
--prefix
```
方便管理生成的图片
合理的 n 值：批量生成时 n=4 是较好的平衡点
图生图参考图：使用单人正面清晰照片，效果最佳

CRITICAL: English prompts yield far better results than Chinese, be sure to use English descriptions
Check quota before batch generation: Use the
```
minimax-usage
```
skill to check balance first
Prompt optimization: Detailed descriptions of scenes, lighting, and styles yield better results
Specify output directory: Use
```
--output-dir
```
to avoid images being scattered in the current directory
Custom filename prefix: Use
```
--prefix
```
to facilitate management of generated images
Reasonable n value: n=4 is a good balance for batch generation
Image-to-image reference image: Use a clear front-facing photo of a single person for best results