motiful/product-shots / skills/product-shots-image-gen
product-shots-image-gen
VerifiedUnified image-generation engine for the product-shots ecosystem. Dispatches to the right model family (OpenAI gpt-image-2 / Gemini gemini-3-pro-image-preview Nano Banana Pro) with one parameterised script for text-to-image and image-to-image. Primary backend: OmniMaaS / Cloubic gateway (https://api.omnimaas.com/v1); also supports any OpenAI-SDK-compatible gateway via fallback env vars. Auto-resizes oversized reference images to prevent edge-proxy timeouts. Use when the user says "generate an image", "make a picture", "create a visual", "render this", "edit this image", "做一张图", "生成图片", "改这张图" — or when invoked as the image-generation backend by another product-shots skill (main-image / detail-page / ad-creative / social-post / multi-angle). NOT a creative-direction skill: takes a prompt + optional reference images, returns a file path.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.7 KB |
| references/error-handling.md | markdown | 5.8 KB |
| references/model-selection.md | markdown | 6.5 KB |
| references/parameter-spec.md | markdown | 7.8 KB |
| references/reference-image-handling.md | markdown | 4.0 KB |
| scripts/generate.pyexecutable | script | 15.3 KB |
| scripts/setup.shexecutable | script | 2.9 KB |
references/parameter-spec.md
View on GitHub---
name: parameter-spec
description: Single source of truth for every CLI flag and Python keyword argument exposed by render — name, type, default, applicability per family, valid range. Includes the aspect-ratio → OpenAI pixel-size lookup table and the per-caller recommendation table. Loaded by the parent SKILL.md's Execution Procedure Step 0 (argument validation) and Step 3 (effective prompt composition).
---
# Parameter Spec
Every flag of `scripts/generate.py`. The validation function below is the authority — if argparse and this spec disagree, this spec wins.
## Execution Procedure
```
validate_args(args) → effective_args | exit
require args.prompt is non-empty AND len(args.prompt) ≤ 4000
require args.model is in OPENAI_MODELS ∪ GEMINI_MODELS
# delegate to model_family() in references/model-selection.md
if args.aspect_ratio:
assert args.aspect_ratio in {"1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3"}
family = model_family(args.model)
if family == "openai":
args.size = args.size OR OPENAI_SIZE_BY_RATIO[args.aspect_ratio] OR "1024x1024"
assert args.n >= 1
elif family == "gemini":
if args.n != 1:
warn "Gemini ignores --n; loop in caller for multiples. Forcing n=1."
args.n = 1
if args.size:
warn "Gemini ignores --size; aspect ratio is embedded in prompt."
for path in args.reference_image:
assert path.exists() AND path.is_file()
return args
```
```
lookup_caller_defaults(caller_skill: str, surface: str) → flag_dict
# Recommended invocation flags per skills caller / surface combination.
# Returns a dict of flag → value that can be passed straight to generate.py.
# See "Family-Specific Defaults" table below.
# Called by SKILL.md Execution Procedure Step 0a, immediately after validate_args,
# to fill caller-context defaults before family routing.
```
```
generate_image(prompt, model, [aspect_ratio], [negative_prompt],
[reference_images], [output_path]) → file_path
# Implemented in scripts/generate.py (main() + generate_openai() / generate_gemini()).
# Top-level entry function for the skill. Covers Step 0 → Step 6 in SKILL.md EP.
# Returns the absolute path of the saved image on disk (PNG for OpenAI family,
# JPEG for Gemini family). Caller treats this path as the canonical artifact.
```
```
load_api_key() → (api_key: str, source_label: str)
# Implemented in scripts/generate.py:load_api_key().
# Resolution order: see "API Key + Base URL" section below.
# source_label is the human-readable origin (e.g., "OMNIMAAS_API_KEY env",
# "~/.product_shots_imagegen_api_key file") used for non-secret logging.
# Exits with a clear message if no key resolves.
```
```
load_base_url() → (base_url: str, source_label: str)
# Implemented in scripts/generate.py:load_base_url().
# Resolution order: see "API Key + Base URL" section below.
# Defaults to https://api.omnimaas.com/v1 when OMNIMAAS_API_KEY is the
# resolved auth source and no explicit base URL env var is set.
```
```
compose_prompt(prompt: str, negative_prompt: str, aspect_ratio: str, family: str) → str
# Implemented in scripts/generate.py:compose_prompt().
# Gemini: appends "(aspect ratio: X:Y)" + "Avoid: <negative>" to the prompt
# (chat-completions has no size field, so ratio rides in the text).
# OpenAI: appends only "Avoid: <negative>" (aspect ratio is routed through the
# pixel `size` param in Step 3 via OPENAI_SIZE_BY_RATIO).
# Returns the effective prompt string sent to the upstream endpoint.
```
## CLI Flags
| Flag | Required | Type | Default | Applicability | Notes |
|---|---|---|---|---|---|
| `--prompt` | **yes** | string | — | both families | The text instruction. ≤4000 chars practical limit. |
| `--model` | **yes** | enum | — | both families | One of the supported model names; see `references/model-selection.md`. Family is auto-derived. |
| `--aspect-ratio` | no | enum | none | both families | `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`. OpenAI: mapped to `size`. Gemini: appended to prompt. |
| `--size` | no | string `WxH` | `1024x1024` | **openai only** | Explicit pixel dimensions. Overrides `--aspect-ratio`. Ignored for Gemini. |
| `--negative-prompt` | no | string | none | both families | Concepts to avoid. Appended to prompt as `Avoid: …`. No API has a true `negative_prompt` field. |
| `--n` | no | int ≥1 | 1 | **openai only** | Number of variations per call. Gemini = always 1; loop in caller for multiples. |
| `--reference-image` | no | path (repeatable) | [] | both families | File path(s). Auto-resized to ≤1024px / ≤1MB. Up to 9 for Gemini per their docs; OpenAI accepts multiple `image[]` entries for `/v1/images/edits`. |
| `--output` | no | path | `./output-<ts>.<ext>` | both families | Where to save. Extension auto-determined (PNG for OpenAI, JPEG for Gemini) when default is used. Parent dirs are created. |
## Aspect Ratio → OpenAI Size Mapping
```
1:1 → 1024x1024
3:2 / 4:3 / 16:9 → 1536x1024 (landscape)
2:3 / 3:4 / 9:16 → 1024x1536 (portrait)
```
This mapping is intentionally coarse — gpt-image-2 only supports a small set of pixel sizes. For exact pixel dimensions, use `--size` directly.
## Family-Specific Defaults
When called by other product-shots specialists:
| Caller / use case | Recommended flags |
|---|---|
| **Any output that must carry on-image text** (headlines / labels / CTAs / price chips / callout annotations) | `--model gpt-image-2` — overrides any default below. Gemini family cannot render small text reliably. See `references/model-selection.md` §Decision Tree (text-overlay branch wins). |
| `product-shots-main-image` (Amazon main image, single SKU) | `--model gpt-image-2 --aspect-ratio 1:1` |
| `product-shots-main-image` (secondary as tech-spec callout with labels) | `--model gpt-image-2 --aspect-ratio 1:1 --reference-image <main.jpg>` |
| `product-shots-main-image` (secondary as pure visual variant, no text) | `--model gemini-3-pro-image-preview --aspect-ratio 1:1 --reference-image <main.jpg>` |
| `product-shots-detail-page` (A+ Hero Banner 21:9) | `--model gemini-3-pro-image-preview --aspect-ratio 16:9 --reference-image <main.jpg>` |
| `product-shots-detail-page` (A+ standard module 3:2) | `--model gemini-3-pro-image-preview --aspect-ratio 3:2 --reference-image <main.jpg>` |
| `product-shots-multi-angle` (9-angle model series) | `--model gemini-3-pro-image-preview --reference-image <model.jpg>` |
| `product-shots-ad-creative` (any platform — UGC, Meta, Google) | `--model gpt-image-2 --aspect-ratio <platform-specific> --reference-image <composition-anchor.jpg>` — ad copy text MUST render legibly, so always gpt-image-2. |
| `product-shots-social-post` (text-bearing — price tag, magazine headline) | `--model gpt-image-2 --aspect-ratio 4:5` |
| `product-shots-social-post` (purely visual Carousel slide, no on-image text) | `--model gemini-3-pro-image-preview --aspect-ratio 4:5` |
## API Key + Base URL
Resolved at runtime in this priority order:
**API key:**
1. `OMNIMAAS_API_KEY` env var (preferred — OmniMaaS / Cloubic gateway)
2. `PRODUCT_SHOTS_IMAGEGEN_API_KEY` env var (canonical generic, any OpenAI-SDK-compatible gateway)
3. `RENDER_API_KEY` env var (short alias)
4. `CANVASFLOW_IMAGEGEN_API_KEY` env var (legacy fallback)
5. `~/.product_shots_imagegen_api_key` file (chmod 600 recommended)
6. `~/.product_shots_render_api_key` file (compat with earlier ship)
7. `~/.canvasflow_imagegen_api_key` file (legacy fallback)
**Base URL:**
1. `OMNIMAAS_BASE_URL` env var
2. `PRODUCT_SHOTS_IMAGEGEN_BASE_URL` env var (canonical generic)
3. `RENDER_BASE_URL` env var (short alias)
4. `CANVASFLOW_IMAGEGEN_BASE_URL` env var (legacy fallback)
5. Default `https://api.omnimaas.com/v1` when `OMNIMAAS_API_KEY` is set without an explicit base URL
Both API key and base URL are **never echoed**, never written to logs. The skill exits with a clear message if either is missing.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |