liangdabiao/ecom-details-image

ecom‑details‑image Skill

What it is – A command‑line‑driven “skill” that helps you create the whole set of visual assets needed for an e‑commerce product page (main product photos, detail‑page images, social‑media banners, live‑stream backdrops, etc.). It works with Claude Code, Codex or WorkBuddy environments and talks to the apiz image‑generation service (or the built‑in imagegen tool in Codex). The skill can either:

1. Generate a visual brief and a ready‑to‑use prompt for an image model, or
2. Call the image model directly and save the resulting pictures.

---

Key concepts

Concept	What it means
Prompt / Brief mode	The skill returns a structured brief (goal, style, conversion drivers, etc.) plus the final prompt and any negative constraints. No image is generated unless you have the apiz CLI installed.
Generate mode	When you ask for “render image” the skill builds the final prompt, creates a Campaign Style Lock (a block of text that forces colour, lighting, font, layout, etc. to stay consistent across the whole set) and then either calls the Codex imagegen tool or runs scripts/generate_image.py which uses the apiz CLI.
Campaign Style Lock	A reusable style description that is injected into every image prompt so the whole bundle looks cohesive.
apiz CLI	A third‑party command‑line client that uploads reference images, submits a generation request to an AI image model (default apiz/gpt-image-2.5-flare), waits for the task to finish and downloads the result.
Image pack rules	By default the skill will output a full e‑commerce package: 5 main product shots and 7‑9 detail‑page images, each with its own prompt file.

---

How to use it

1. Install the apiz CLI (if you want automatic image generation):

   apiz --version   # verify installation
   apiz auth login  # store your API key
   

2. Clone the repository and navigate to its root.
3. Run the skill (via your AI‑assistant environment) and ask for either a brief or a full image set. Example prompts you can give the assistant: “Generate a visual brief and prompt for a premium‑look Amazon main image of a self‑heating eye mask.” “Render the full image pack for a laundry pod product, using the configured API.”
4. If you asked for generation, the skill will:
   • Build the final prompt(s).
   • Create the Campaign Style Lock.
   • Call imagegen (Codex) or execute python3 scripts/generate_image.py … (apiz).
   • Save the images under generated-images/ (or a folder you specify) and return the file paths.

---

Command‑line helper (scripts/generate_image.py)

Option	Description
--prompt "…"	Prompt string directly on the command line.
--prompt-file FILE	Read the prompt from a text file.
--output-dir DIR	Where to store the generated pictures (default generated-images/).
--size RATIO	Aspect ratio (1:1, 4:5, 16:9, etc.) – also accepts pixel forms like 1024x1024.
--model MODEL_ID	Image model to use (default apiz/gpt-image-2.5-flare).
--image PATH	Local reference product photo – will be uploaded to apiz CDN first.
--image-url URL	Public URL of a reference image (takes precedence over --image).
--timeout SEC	Max seconds to wait for the apiz task (default 420).
--format EXT	File extension for saved images (default png).
--env-file FILE	Load environment variables from a custom .env file.

Typical call:

python3 scripts/generate_image.py \
  --prompt-file prompt.txt \
  --size 4:5 \
  --model apiz/gpt-image-2.5-flare \
  --image data/product.jpg \
  --output-dir outputs

---

Limitations & safety notes

• Cost – Each image consumes apiz credits (≈30‑90 s per picture). Check your balance with apiz account balance before large batches.
• Async generation – The CLI waits (--wait) for the task, but the underlying URL is temporary; the script downloads the file locally.
• No secret leakage – The repo never stores API keys; they must be provided via the apiz CLI login or an environment variable.
• Content policy – The skill adds negative constraints (e.g., “no readable text”) and warns you not to fabricate certifications or test results in the visual copy.
• Model‑dependent resolution – Output pixel dimensions depend on the chosen model (default supports up to 4K).

---

Who might find this useful?

• E‑commerce merchants who need a fast way to produce a consistent set of product images for Amazon, Shopify, TikTok Shop, etc.
• Marketing teams looking for AI‑generated ad banners, social‑media graphics, or live‑stream backdrops.
• Developers of AI‑assistant bots who want to embed a ready‑made image‑generation skill without writing their own integration code.

---

Quick start checklist

1. Install apiz CLI and log in.
2. Clone the repo.
3. In your AI assistant, request a brief or a full image pack.
4. If you asked for generation, locate the files under generated-images/.
5. Review the visual brief, tweak prompts if needed, and run A/B tests on the produced assets.