AI agent skill

Install one skill and your AI agent can generate images in bulk on your behalf — choosing a model, estimating the cost, asking you to confirm the spend, then submitting, polling and downloading the batch.

Create an API key API docs

What it does

A skill is a folder of instructions your agent reads when a task matches. This one teaches it the whole BulkImagen workflow, so you can ask for images in plain language instead of writing API calls.

For example

“Generate 12 product shots of this mug on a marble table, 16:9.”

The agent reads the model catalog, works out that 12 images at 1K costs 60 credits, checks your balance, shows you both numbers and waits. Say yes and it uploads the reference photo, submits the batch, polls until it finishes and saves the files locally.

Install

One command. It detects which agent you use from the current directory, then drops the skill where that agent looks for it — creating a directory and downloading files, nothing else.

curl -fsSL https://bulkimagen.com/skill/install.sh | sh

Piping a script into a shell deserves a look first. Here is exactly what runs: install.sh

Pick your agent explicitly

Detection covers the common cases, but say it outright if you have more than one agent installed. Same content in all three — only the format and the drop point differ.

Claude Code

~/.claude/skills/bulkimagen/

curl -fsSL https://bulkimagen.com/skill/install.sh | sh -s -- claude

Cursor

.cursor/rules/bulkimagen.mdc

curl -fsSL https://bulkimagen.com/skill/install.sh | sh -s -- cursor

Codex · Copilot · Gemini CLI · Aider · Windsurf · Zed

AGENTS.md

curl -fsSL https://bulkimagen.com/skill/install.sh | sh -s -- agents

Add your API key

The skill reads the key from an environment variable and never writes it to disk. API access is on paid plans.

export BULKIMAGEN_API_KEY=bik_live_...

How the agent uses it

Every run follows the same four beats, in this order. The skill is explicit about it so the agent doesn't improvise with your credits.

1
Read the catalog
It fetches the live model list rather than relying on remembered names or prices, and reads which aspect ratio is legal at which resolution.
2
Estimate and confirm
It works out how many images the batch produces and what that costs, compares it to your balance, and stops for your explicit yes. This step is not optional.
3
Submit and poll
Reference images upload first (free), then the batch is created and credits are charged. It polls every few seconds until nothing is pending or running.
4
Download and report
Result images are saved locally. Failed tasks are refunded automatically, and the agent tells you about them instead of quietly dropping them.

Guardrails

An agent holding an API key is spending real money on your behalf. Three rules are written into the skill itself.

Always confirms the spend

The agent must show the image count and the credit cost, then wait for you — even if you said “just do it” earlier. The bundled CLI enforces the same thing: without --yes it exits instead of submitting.

Never leaks the key

The key is read from BULKIMAGEN_API_KEY, never printed, written into a file, or passed where shell history would capture it. Set a per-key daily credit cap for an extra bound.

Won't loop on hard failures

Blocked prompts, exhausted credits and plan limits are marked non-retryable. The agent reports the reason and stops rather than burning through your balance retrying.

What gets installed

The Claude Code install lays down four files. Cursor and AGENTS.md installs are a single self-contained file that links back to the rest.

bulkimagen/
├── SKILL.md
├── references/
│   ├── api.md
│   └── choosing-a-model.md
└── scripts/
    └── bulkimagen.mjs

File	What it is
`SKILL.md`	When to trigger, the workflow, and the spend guardrails.
`references/api.md`	Every endpoint, parameter and error code.
`references/choosing-a-model.md`	Which model fits which job, and the traps to avoid.
`scripts/bulkimagen.mjs`	Zero-dependency CLI (Node 18+) for submit, poll and download.

The CLI on its own

The bundled script also works without an agent — useful in a shell or a cron job. It prints a cost estimate and refuses to submit unless you pass --yes.

node ~/.claude/skills/bulkimagen/scripts/bulkimagen.mjs \
  submit --model nano-banana-pro --count 4 --ratio 16:9 \
  --out ./images --yes "a red fox in snow"

Using a different agent

The skill format targets Claude Code, but nothing about the API is specific to it. Any agent that can read a page and make HTTP calls can use the plain-text reference or the OpenAPI spec directly.

Plain-text reference OpenAPI spec