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

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-nano)
--dry-run	-n	Preview only, don't rename files
--yes	-y	Skip confirmation prompt

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

Supported Formats

PNG, JPG, JPEG, GIF, WEBP

How It Works

Uses OpenRouter's vision models to analyze images and generate appropriate filenames. The response is validated using Pydantic structured outputs to ensure consistent, sanitized filenames (lowercase, hyphens instead of spaces, no special characters).