ayan-image-optimizer

Interactive local image optimization with Ollama or OpenAI filename generation.

Install and run

npm install
npm run aio -- ./images --width 1920

aio is a short alias for ayan-image-optimizer.

After publishing, install and run it globally with:

npm install -g ayan-image-optimizer
aio ./images --width 1920

Omit --width to keep every source image's current dimensions. Choose original to optimize each image while retaining its current format (for example, PNG to PNG). Choose all to create WebP, AVIF, and the original format. Outputs are named seo-name.<format>; when --width is supplied, they are named seo-name-width.<format>.

Generate several responsive widths in one run with comma-separated values:

aio ./images --width 480,960,1920

For an image named mountain.jpg, this can create files such as mountain-480.webp, mountain-960.webp, and mountain-1920.webp in images/optimized/.

First run

The CLI supports Ollama, OpenAI, and OpenAI-compatible APIs. Select openai-compatible to enter a compatible base URL, model, and optional API key. It saves all settings, including API keys, in config.json. Use aio --reconfig to update the provider, model, endpoint, or API key later. Add an image folder to continue processing after the update: aio ./images --reconfig. Do not commit this file. Copy the example file if you prefer to configure it before running:

cp config.example.json config.json

Connector examples

The simplest way to configure a connector is interactive:

aio --reconfig

Ollama (local)

Pull a model, then select ollama during reconfiguration:

ollama pull gemma3
aio --reconfig

Use these values when prompted:

{
  "ai": { "provider": "ollama", "model": "gemma3" },
  "ollama": { "baseUrl": "http://127.0.0.1:11434" }
}

OpenAI API

Select openai, keep the default base URL, choose an available API model, and provide an API Platform key:

{
  "ai": {
    "provider": "openai",
    "model": "gpt-5.6-luna",
    "baseUrl": "https://api.openai.com/v1",
    "apiKey": "YOUR_OPENAI_API_KEY"
  },
  "ollama": { "baseUrl": "http://127.0.0.1:11434" }
}

LM Studio (OpenAI-compatible)

Start LM Studio's server and load a model, then select openai-compatible:

lms server start
aio --reconfig

LM Studio's OpenAI-compatible API defaults to port 1234; local authentication is off by default, so leave apiKey empty unless you enabled it:

{
  "ai": {
    "provider": "openai-compatible",
    "model": "openai/gpt-oss-20b",
    "baseUrl": "http://localhost:1234/v1",
    "apiKey": ""
  },
  "ollama": { "baseUrl": "http://127.0.0.1:11434" }
}

Any service that implements GET /v1/models and POST /v1/chat/completions can be configured the same way: use openai-compatible, its API base URL, its model ID, and its required API key.

While connecting to the selected AI provider and generating filenames, the terminal displays rotating status messages so it is clear that processing is active.

Descriptions can be entered in Persian/Farsi (RTL), English, or a mix of both. The CLI provides an RTL-aware description prompt and formats Persian output for terminals that otherwise draw it left-to-right. At the end of a successful run, it prints SEO-friendly English and Persian alt text for every source image. The same AI request generates the filename and both alt texts.

Only JPEG, PNG, WebP, and AVIF inputs are processed. GIF and SVG files are reported as skipped. Originals are never changed.