Image Namer

AI-powered image filename generator using OpenRouter Vision models.

Features

• Generate descriptive filenames for images using AI
• Three profile modes: short (2-4 words), normal (4-7 words), detailed (7-12 words)
• Process single or multiple images with shell expansion support
• Parallel processing (default: 16 concurrent requests)
• Renames files by default with confirmation prompt
• Configurable filename length limits
• Structured output validation with Pydantic

Installation

This is a PEP 723 script - dependencies are declared inline and managed automatically by uv.

1. Set up the bash wrapper for easy access:

# Symlink the wrapper to your scripts directory
ln -s /path/to/image-namer/image-namer-wrapper.sh ~/scripts/

2. Source your scripts (or restart your shell):

source ~/scripts/image-namer-wrapper.sh

Now you can use the imgname command.

Usage

Set your OpenRouter API key:

export OPENROUTER_API_KEY="your-api-key-here"

Basic usage:

# Single image (renames by default, asks for confirmation)
imgname photo.jpg

# Multiple images with shell expansion
imgname *.jpg

# Short filenames (2-4 words)
imgname photo.jpg --short

# Detailed filenames (7-12 words)
imgname photo.jpg --detailed

# Preview without renaming
imgname photo.jpg --dry-run

# Skip confirmation prompt
imgname photo.jpg -y

# Custom instruction
imgname photo.jpg -i "focus on the colors and mood"
imgname *.png -i "include the number of people visible"

Or run directly with uv:

uv run image-namer.py photo.jpg

Options

Option	Short	Description
--short	-s	Use short profile (2-4 words)
--detailed	-d	Use detailed profile (7-12 words)
--max-length	-l	Maximum filename length (default: 50)
--model	-m	OpenRouter model to use (default: openai/gpt-5.6-luna)
--dry-run	-n	Preview only, don't rename files
--yes	-y	Skip confirmation prompt
--parallel	-p	Max parallel requests (default: 16)
--instruction	-i	Custom instruction for filename generation

Note: --short and --detailed are mutually exclusive.

Supported Formats

PNG, JPG, JPEG, GIF, WEBP

How It Works

Uses OpenAI GPT-5.6 Luna through OpenRouter to analyze images and generate appropriate filenames by default. You can select another OpenRouter model with --model. The response is validated using Pydantic structured outputs to ensure consistent, sanitized filenames (lowercase, hyphens instead of spaces, no special characters).