MiniMax Image Text-to-Image Skill

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

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

Required environment variables:

bash

export MINIMAX_API_KEY="your_api_key_here"

Optional environment variables:

bash

# API host address (default for domestic sites is https://api.minimaxi.com)
export MINIMAX_API_HOST="https://api.minimaxi.com"

Usage

Text-to-Image

bash

# Basic usage - generate 1:1 square image
bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "a cute fluffy cat sitting on a windowsill"

# 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

# Vertical ratio (9:16 suitable for mobile wallpapers)
bun run ${CLAUDE_SKILL_DIR}/scripts/generate.ts "futuristic city skyline" --aspect-ratio 9:16

# 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

Image-to-Image (Maintain Subject Consistency)

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

bash

# 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: 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 Parameter Description

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 Parameters

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

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

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 - Chinese prompts yield poor results

bash

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

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

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

bash

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

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

❌ 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

✅ 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

Error Handling

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

Best Practices

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

minimax-image

NPX Install

Tags

SKILL.md Content (Chinese)

MiniMax Image Text-to-Image Skill

Quick Reference

Prerequisites

Usage

Text-to-Image

Image-to-Image (Maintain Subject Consistency)

API Parameter Description

CLI Parameters

Supported Aspect Ratios

subject_reference Parameter Description

❌ WRONG / ✅ CORRECT

❌ WRONG - Chinese prompts yield poor results

✅ CORRECT - English prompts yield better results

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

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

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

✅ CORRECT - Specify output directory and filename prefix

Error Handling

Script Help

Best Practices