{
  "markdown": "# bulk-image-generation — Claude Code skill\n\nOrchestrated bulk AI image generation for [Claude Code](https://claude.com/claude-code) via [Pollinations.ai](https://pollinations.ai/). Built for seeding demo datasets (patient avatars, product photos, dermatology references, etc.) without juggling manual downloads, URLs, or browser tabs.\n\nClaude asks you for a prompt (or drafts a professional one from your description), confirms the parameters, then runs a Python helper that:\n\n- hits Pollinations sequentially with polling on transient errors\n- writes every image to a user-specified output directory\n- serves a **live HTML dashboard** you open via `file://` that auto-refreshes every 2s while the run is in progress\n- emits JSON-lines events to stdout so Claude Code's `Monitor` tool can stream progress in chat\n- persists a `run.json` next to the images with all the parameters, for later recovery\n- optionally uses **your own Pollinations API key** (stored locally, entered via a one-shot local web form — never pasted into chat)\n\nStdlib-only Python. No `pip install` anything.\n\n## Install\n\n### Via Claude Code plugin marketplace\n\n```text\n/plugin marketplace add christianpasinrey/bulk-image-generation-skill\n/plugin install bulk-image-generation@bulk-image-generation-marketplace\n```\n\n### Manual (drop-in)\n\n1. Clone or download the repo.\n2. Copy the entire `skills/bulk-image-generation/` directory to `~/.claude/skills/`:\n   ```bash\n   cp -r skills/bulk-image-generation ~/.claude/skills/\n   ```\n   Windows:\n   ```\n   xcopy /E /I skills\\bulk-image-generation %USERPROFILE%\\.claude\\skills\\bulk-image-generation\n   ```\n3. Make sure Python 3.10+ is on your PATH.\n4. Open a fresh Claude Code session. The skill is auto-detected.\n\n## Prerequisites\n\n- **Claude Code** (any recent version with skill support)\n- **Python 3.10+** (`python --version`)\n- No pip dependencies — everything uses stdlib (`urllib`, `http.server`, `json`, `pathlib`, …)\n\n## Usage\n\n### From Claude Code (natural)\n\n> \"Necesito 20 retratos de pacientes masculinos para el seeder demo en `storage/app/demo/avatars/male`\"\n\nClaude detects the trigger, asks whether to use the public API or your own key, confirms the prompt, launches the Python helper in the background, gives you the dashboard URL to open in your browser, and reports the final count when it finishes.\n\n### Direct CLI usage\n\nThe Python helper works standalone too — no Claude Code needed.\n\n```bash\n# Fresh generation run\npython ~/.claude/skills/bulk-image-generation/generate.py \\\n  --prompt \"simple red apple on plain white background, product photography\" \\\n  --count 10 \\\n  --model flux \\\n  --width 768 --height 768 \\\n  --output ~/bulk-test\n```\n\nOutput layout:\n\n```\n~/bulk-test/\n├── 001_flux_12345.jpg     # generated image\n├── 002_flux_12346.jpg\n├── …\n├── dashboard.html         # open with your browser (auto-refreshes during the run)\n└── run.json               # full run metadata + per-seed status\n```\n\n## Recovery mode\n\nPollinations caches every image by URL hash (`prompt + model + seed + width + height`). Requesting the same URL again returns the cached bytes in ~1 second without re-generating. Two ways to tap the cache:\n\n**A. Known seed base**\n\n```bash\npython ~/.claude/skills/bulk-image-generation/generate.py \\\n  --recover \\\n  --prompt \"THE ORIGINAL PROMPT\" \\\n  --seed 12345 \\\n  --count 20 \\\n  --model flux \\\n  --width 1024 --height 1024 \\\n  --output /new/destination\n```\n\nThe prompt must be byte-identical to the original run. The script's URL encoder matches JavaScript's `encodeURIComponent()` exactly so runs seeded from other tools (web-based bulk generators, etc.) hit the same cache entries.\n\n**B. From a previous `run.json`**\n\n```bash\npython ~/.claude/skills/bulk-image-generation/generate.py \\\n  --from /path/to/previous/run.json \\\n  --output /new/destination\n```\n\n`--from` pulls prompt, model, dimensions, seed base and count from the JSON and implies `--recover`.\n\n## Using your own Pollinations API key\n\nThe public API is free but rate-limited and shared across every anonymous caller. If you have a Pollinations token (free tier available at [auth.pollinations.ai](https://auth.pollinations.ai)) you can use it for higher limits and priority queue.\n\n**Setup once:**\n\n```bash\npython ~/.claude/skills/bulk-image-generation/generate.py --set-token\n```\n\nThe script starts a tiny HTTP server on `127.0.0.1`, picks a free port, and emits a `token-server-ready` event with the URL. Open it in your browser, paste your token, click Save. The token lands in `~/.bulk-image-generation/config.json` (mode `0600` where supported) and the server shuts itself down.\n\n**Use it on runs:**\n\n```bash\npython generate.py --prompt \"…\" --count 10 --output /out --auth\n```\n\n**Check / clear / inspect:**\n\n```bash\npython generate.py --show-config    # is a token saved?\npython generate.py --clear-token    # delete the saved token\n```\n\nWhen invoked from Claude Code, the skill walks you through this flow automatically: before any generation it asks whether to use the public API or your key, and if you chose your key with none saved it launches `--set-token` and hands you the URL.\n\n## Models\n\n| Model | Speed | Quality | Notes |\n|---|---|---|---|\n| `flux` | Medium | High | Default. Best balance. |\n| `turbo` | Fast | Medium | Good for rapid iteration. |\n| `gptimage` | Medium | High | DALL-E style. |\n| `seedream` | Medium | High | Realistic. |\n\n## Troubleshooting\n\n**HTTP 500 on recovery mode but I know the image was generated**\n- The prompt hash differs even by one character. Check for trailing spaces, different line endings, or markdown bolding (`**…**`) that were stripped from the original.\n- Copy the prompt literally from wherever the original run lived. If it came from a web tool, check the browser's network tab for the exact URL the tool sent.\n\n**Rate limit (HTTP 429) very frequent**\n- Pollinations throttles per IP. If you're running two bulk tools in parallel from the same connection, you're throttling yourself.\n- Bump `--poll-wait` (default 20s) to 30-45s and `--delay` (default 5s between images) to 10s.\n- Or register a token and use `--auth` for higher limits.\n\n**Token setup URL opens but the form POST fails**\n- The server binds `127.0.0.1` only. Don't try to access it via LAN IP — browser must be on the same machine.\n- If the port is in use by something else, re-run `--set-token` and it will pick a new free port.\n\n**The skill doesn't appear in Claude Code**\n- Verify the folder is exactly `~/.claude/skills/bulk-image-generation/` with `SKILL.md` + `generate.py` inside.\n- Start a fresh session — some Claude Code versions cache the skill list at boot.\n\n## Repository layout\n\n```\nbulk-image-generation-skill/\n├── .claude-plugin/\n│   ├── plugin.json          # plugin manifest\n│   └── marketplace.json     # marketplace catalog (single-plugin)\n├── skills/\n│   └── bulk-image-generation/\n│       ├── SKILL.md         # workflow + trigger metadata consumed by Claude Code\n│       └── generate.py      # the actual worker, stdlib-only\n└── README.md                # this file\n```\n\n## Contributing\n\nIssues and PRs welcome. Keep in mind:\n\n- Python stdlib only — no new dependencies.\n- Any new flag should be covered in both `SKILL.md` (workflow instructions) and this `README.md` (user reference).\n- Events emitted to stdout are a public interface: don't rename existing event names without bumping the major version.\n\n## Third-party\n\nUses [Pollinations.ai](https://pollinations.ai/) as the image backend — free public image endpoint. Review their terms and content policy before generating anything sensitive.\n",
  "bytes": 7578,
  "sha": "826f678b5e64a6ae779d487be1b8ad8d501d206e73abb0c556f845ff40fb3ae2",
  "repo_slug": "christianpasinrey/bulk-image-generation-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_christianpasinrey_bulk_image_generation__af6bd892/readme"
}