---
slug: "zgltyq-pi-minimax-image"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/zgltyq/minimax-understand-image@main/README.md"
repo: "https://github.com/zgltyq/minimax-understand-image"
source_file: "README.md"
branch: "main"
---
# pi-minimax-image

MiniMax Image Understanding extension for [pi coding agent](https://github.com/badlogic/pi-mono) — provides AI-powered image understanding **as a fallback for models without native vision support**.

> ⚠️ **Use only when the model does not natively support image understanding.** Many models (Claude, Gemini, GPT-4V) can process images directly via the `read` tool. This extension's `understand_image` tool routes images through the MiniMax API — use it only when the model you're running cannot natively see images.

## Why This Package?

**Built for image understanding fallback.** While [pi-web-access](https://www.npmjs.com/package/pi-web-access) handles web search and URL fetching, this package specializes in AI-powered image analysis for models without built-in vision.

**Use this package when you need to:**
- 📸 Analyze screenshots, diagrams, and UI mockups
- 🔤 Extract text from images (OCR)
- 🖥️ Transcribe code from screenshots
- 🎨 Get AI descriptions of visual content
- 📊 Analyze charts, graphs, and data visualizations

**No conflicts.** This extension only provides `understand_image` - it won't interfere with other packages like `pi-web-access`.

## Features

- 🖼️ **Image Understanding** - Analyze images with AI for descriptions, OCR, code extraction, and visual analysis
- ⚡ **Easy Configuration** - Configure via environment variables or pi settings files
- 🔄 **Hot Reload** - Changes apply without restarting pi
- 🎨 **Rich UI** - Custom rendering with progress indicators and status updates
- ✅ **Focused** - Only adds image understanding, no bloat

## Prerequisites

- [pi coding agent](https://github.com/badlogic/pi-mono) installed
- [MiniMax Coding Plan subscription](https://platform.minimax.io/subscribe/coding-plan)
- Node.js >= 18.0.0

## Installation

```bash
pi install npm:@zgltyq/pi-minimax-image
```

Or via git:

```bash
pi install git:github.com/zgltyq/minimax-understand-image
```

## Configuration

### Get Your API Key

1. Visit [MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan) to subscribe
2. Get your API key from [API Key page](https://platform.minimax.io/user-center/payment/coding-plan)

### Environment Variable

```bash
export MINIMAX_API_KEY="your-api-key-here"
```

### Auth File

Save to `~/.pi/agent/auth.json`:
```json
{
  "minimax": {
    "type": "api_key",
    "key": "your-api-key-here"
  }
}
```

### Interactive Setup

```bash
/minimax-configure --key your-api-key-here
```

## Usage

### Image Understanding

```
understand_image({
  prompt: "What error is shown in this screenshot?",
  image_url: "https://example.com/error.png"
})
```

#### Image Sources

- HTTP/HTTPS URLs: `"https://example.com/image.jpg"`
- Local paths: `"/home/user/image.png"` or `"./screenshot.jpg"`

#### Example Use Cases

```typescript
// Describe image content
understand_image({
  prompt: "Describe what's in this image in detail",
  image_url: "https://example.com/photo.jpg"
})

// Extract text (OCR)
understand_image({
  prompt: "Extract all text from this image",
  image_url: "./screenshots/document.png"
})

// Analyze UI/UX
understand_image({
  prompt: "Analyze this UI design and suggest improvements",
  image_url: "https://example.com/mockup.png"
})

// Code from screenshot
understand_image({
  prompt: "What code is shown in this screenshot? Transcribe it exactly.",
  image_url: "./error-screenshot.jpg"
})

// Analyze data visualizations
understand_image({
  prompt: "What trends and insights can you extract from this chart?",
  image_url: "./analytics.png"
})
```

## Tool Reference

### understand_image

| Parameter | Type   | Required | Description                                      |
| --------- | ------ | -------- | ------------------------------------------------ |
| prompt    | string | ✓        | Question or analysis request (1-1000 characters) |
| image_url | string | ✓        | Image URL or local file path                     |

## Commands

| Command              | Description                |
| -------------------- | -------------------------- |
| `/minimax-configure` | Configure API key          |
| `/minimax-status`    | Show configuration status  |

## Related Packages

- [pi-web-access](https://www.npmjs.com/package/pi-web-access) - Web search, URL fetching, GitHub repos, YouTube videos, PDFs

## Learn More

- [MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan)
- [pi coding agent](https://github.com/badlogic/pi-mono)

## License

MIT