image-sourcer: on-demand image generation

Ad creative (utility) Desktop

What it does

image-sourcer is the image-generation engine the rest of the toolkit runs quietly in the background. When a page build or ad skill needs a hero image, a product shot, or a lifestyle scene, it calls image-sourcer. You rarely invoke it directly, and that’s intentional: the skills that use it (like page builds and ad creative) already know the right prompts, aspect ratios, and reference images for the job.

That said, it’s available directly when you need a single image fast and don’t want to run a full skill for it.

It’s a sibling to creatify-batch: creatify-batch runs batches of Creatify ad images, while image-sourcer handles Gemini-powered generation for pages and utility tasks.

When to reach for it directly

You need one quick image (a lifestyle scene, a background, a product context shot) outside of a full page or ad build.
You want to test a prompt before committing it to a larger batch.
A skill’s output included a placeholder image and you want to regenerate just that one.
You need a reference-grounded product image and want to call the generator directly to inspect the result.

Most of the time, you won’t call it directly. If you’re running a page build or ad skill, image-sourcer is already in the loop.

Where it runs

Desktop only

image-sourcer calls an outside image service (Google Gemini). Cowork’s sandbox blocks outbound API calls to that service today, so this skill runs on the Claude Code desktop app with a Gemini API key configured.

If you haven’t set up your Gemini key yet, see API keys setup.

How to run it

Ask directly, describing what you need:

“Generate a lifestyle image of someone unwinding at home in the evening, warm lighting, 4:5 ratio, save to my project folder”

Or if you need a product-grounded image, point it at the real product:

“Use image-sourcer to generate a hero shot for examplebrand.com’s protein powder. Use the product photo at examplebrand.com/images/product.png as a reference.”

You can specify:

Aspect ratio: 4:5 (feed ad), 9:16 (Reels/Stories), 16:9 (hero banner), 1:1 (square)
Output location: a folder path for the generated file
Reference image: a URL or local file path, so the output depicts the real product rather than a generic lookalike

What it needs from you

A clear prompt. The more specific, the sharper the image: subject, setting, lighting, mood, and what the image is for.
(Optional) Aspect ratio. Defaults to a sensible square if you don’t specify.
(Optional) A reference image. Required whenever the output needs to show a specific branded product. Without a reference, the model generates a plausible-looking generic, not your actual product.

What you get back

An image file saved to the output location you specified (or an ai-generated-<timestamp>.png in the folder if you didn’t name it).
If the image doesn’t match what you wanted, just re-prompt. Text-heavy or product-specific images sometimes need one or two tries to land.

A worked example

You: “Generate a 4:5 lifestyle shot of a woman in her 40s winding down before bed, holding a glass of water, soft warm lamplight, calm and quiet mood.”

image-sourcer: (generates via Gemini Imagen 4)

Saved to ./assets/images/ai-generated-1718234567.png

(You review it. The lighting is right but the composition is a bit flat. You re-prompt with “add a bedside table with a book and a small plant for depth.” Second output nails it.)

That image is now ready to drop into your page build or ad creative.

Tips & gotchas

Output is a directory, not a filename. Pass --filename if you want a specific name, otherwise the script writes ai-generated-<timestamp>.png into the folder. Build agents sometimes forget this and reference the wrong filename. If an image is 404ing after a build, check whether the file landed inside an unexpected subdirectory.
Reference images are not optional for branded products. Without a --ref-images input pointing at the real product, the model generates a plausible generic (wrong label, wrong color, missing branding). Always pass a real product URL or local file path for any image that needs to show the actual product.
Gemini API key must be set. The script exits with a setup message if GEMINI_API_KEY is missing. See API keys setup. No key, no images.
You need the requests package. If it isn’t installed, the script exits with a one-line fix: pip3 install requests. It won’t crash cryptically.
Most users never call this directly. Page builds and ad skills call it for you. If you’re running a full skill and images aren’t generating, the issue is usually the missing API key or a blocked network, not something to fix by calling image-sourcer manually.

image-sourcer is called automatically by page and ad build skills. If you’re running a full page build, see page-architect or assessment-builder. For Creatify-powered ad image batches, see creatify-batch.