Skip to content

motiful/product-shots / skills/product-shots-image-gen

product-shots-image-gen

Verified

Unified 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.

FileKindSize
SKILL.mdskill md16.7 KB
references/error-handling.mdmarkdown5.8 KB
references/model-selection.mdmarkdown6.5 KB
references/parameter-spec.mdmarkdown7.8 KB
references/reference-image-handling.mdmarkdown4.0 KB
scripts/generate.pyexecutablescript15.3 KB
scripts/setup.shexecutablescript2.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.
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: 472kUpdated Claude CodeCodexUnverifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall