Generate and push HTML alt text for Cloudinary images using OpenAI Vision. Fetches your image resource list from Cloudinary, downloads images, generates concise alt text with GPT, and writes alt context back to Cloudinary—all in discrete steps you can run independently.

• List – Retrieve image resources from your Cloudinary cloud via the Admin API and save a resource list (folder structure preserved).
• Download – Download images from that list to a local directory (optimized URLs for fast, small files).
• Generate – Produce one short alt sentence per image using OpenAI Vision (rate-limited, with placeholders on failure).
• Push – Update Cloudinary assets with the generated alt text via the Upload API (add context).
• Test – Run a full pipeline against the Cloudinary demo cloud with simulated generation and push (no API keys required).

Each step is a separate task so you can run only what you need, re-run steps, or plug in your own resource list or alt file.

• Node.js 18+ (for native fetch if used; otherwise 16+)
• OpenAI API key (for the generate task)
• Cloudinary account (for list and push; cloud name can be inferred from resource list URLs for download/generate)

git clone <repo-url>
cd alt-tagger
npm install

Copy the example env file and set your keys and options:

cp .env-example .env

Edit .env (never commit it; it’s in .gitignore).

Optional (defaults shown):

Any option can be overridden on the command line (e.g. --input, --output, --limit, --verbose).

All commands use a task as the first argument. Options follow the task.

node index.js <task> [options]

# Run the full pipeline (each step separately)
node index.js list
node index.js download --limit 50
node index.js generate
node index.js push

# Or use npm script for push only
npm run push-alt

# Test without any API keys (demo cloud, simulated generation and push)
node index.js test
node index.js test --verbose

# Override paths and limits
node index.js list --output my-resources.json
node index.js download --input my-resources.json --limit 10
node index.js generate --input my-resources.json --output my-alts.json
node index.js push --input my-alts.json --limit 5

# Verbose logging
node index.js download -v

npm run test:connections

This script checks that OPENAI_API_KEY works and that Cloudinary (and optionally your cloud) is reachable.

• Resource list (e.g. cloudinary-resources.json): JSON object keyed by folder; each value can have a resources array and/or nested folders. Each resource has at least public_id and secure_url. The list task writes this format; download and generate read it.
• Alt file (e.g. alt-tags.json): JSON object mapping public_id (string) to alt text (string). The generate task writes it; push reads it. Entries like [error: ...] or [download failed or missing] are skipped on push.

• OpenAI
  • API keys
  • Chat Completions (Vision)
  • Node.js / OpenAI SDK
• Cloudinary
  • Dashboard (cloud name, API key, secret)
  • Admin API – List resources
  • Upload API – Add context (metadata)
  • Node.js SDK
  • URL generation (Node)

GNU General Public License v3.0 (GPL-3.0). See LICENSE for the full text.