Product Image Generation

Unified Entry: Full-category e-commerce image generation capability for non-apparel products (cosmetics, digital products, home goods, food, etc.). Both single-image direct generation & image set orchestration are accessed through this skill.

Entry Routing

Condition	Path	Operation
Only one specific type of image is needed (e.g., "create a white background image")	Single-image Direct Generation	Confirm type → Read corresponding `references/types/<type>.md` → Execute shared pipeline
Multiple images / multiple types / image sets are needed (e.g., "create an image set" "generate 5 images")	Image Set Orchestration	Read `references/runtime/00-index.md` → Read `01-plan` / `02-confirm` step by step → Call `scripts/run_collection_pipeline.py` three phases (plan / dispatch / summary, agent sends 3 Bash commands in sequence; dispatch uses `ThreadPoolExecutor` at skill layer to run `scripts/run_one_task.py` concurrently, agent itself does not run concurrently; Prohibit reading `maintainer/collection/` or reading `types/*.md` during image set phase)

Type Routing Table

type	Name	Associated with Selling Points	Has Scene Description	Default Ratio	Details Reference
WHITE_BG	White Background Image	No	No	1:1	`references/types/white-bg.md`
SCENE	Scene Image	Yes	Yes	1:1	`references/types/scene.md`
CLOSE_UP	Close-up Image	Yes	Yes	1:1	`references/types/close-up.md`
SELLING_POINT	Selling Point Image	Yes	Yes	1:1	`references/types/selling-point.md`
PREMIUM_APLUS	Premium A+ Image	Yes	Yes	1464:600	`references/types/aplus.md`
STANDARD_APLUS	Standard A+ Image	Yes	Yes	970:600	`references/types/aplus.md`
PHONE_APLUS	Mobile A+ Image	Yes	Yes	600:450	`references/types/aplus.md`

After confirming the type, must Read the corresponding type reference file to obtain the step 2 differential logic and prompt template for that type, prohibit skipping.

Inapplicable Scenarios

Apparel / model-related images (tops/bottoms/dresses/outerwear/shoes & hats, etc.) → Use
```
linkfox-aigc-imagegen-cloth
```
series.
Pure image editing operations (background replacement, watermark removal, angle change, etc. with clear creative directions) → Use
```
linkfox-aigc-imagegen
```
.
Pure text generation →
```
linkfox-aigc-textgen
```
.
Video generation →
```
linkfox-aigc-videogen
```
.

Shared Pipeline

All types follow the same 3-step pipeline, with differences defined by each type reference.

Step 1: Verify Image URL Accessibility (Universal for All Types)

Input:
```
imageUrls
```
Empty Array Guard (Mandatory): If
```
imageUrls
```
is an empty array / missing / all invalid, stop immediately, do not call downstream with empty images. Prioritize supplementing from context (original image paths uploaded by the user in current/historical rounds); if still unable to supplement, truthfully report an error to the user and request re-upload, prohibit continuing execution with empty
```
imageUrls
```
.
Operation: Check each value in
```
imageUrls
```
one by one (maintain original order): if it is already a public URL (starts with http/https) → directly pass through; if it is a local file path (non http/https) → call
```
linkfox-file-upload
```
to upload and obtain a public URL for replacement.
Output:
```
imageUrls
```
(all are publicly accessible HTTPS URLs)

Step 2: Construct Final Prompt (Differences See Each Type Reference)

The step 2 logic varies by type (whether to call textgen, which model to use, whether to avoid sensitive words, etc.), see the Read

references/types/<type>.md

for details.

White Background Image Static Direct Generation Constraint (WHITE_BG): Use
scripts/build_imagegen_prompt.py --type WHITE_BG
to build the imagegen parameter file. The script will automatically extract the white background image static text from the
text
code block in
references/types/white-bg.md
as the final prompt. The text is long, always let the script read it, do not manually copy or pass via shell variables.
Textgen Chain Call Constraint (Applicable to All Types Except White Background Image): For types that need to call
linkfox-aigc-textgen
, must use this skill's
build_textgen_params.py
auxiliary script to build the textgen parameter file (the script automatically completes template reading, placeholder filling, model/thinkingLevel setting, sensitive word avoidance instruction appending), then execute according to the chain call method in textgen SKILL.md.
Image Set Must Go Through Pipeline Three Phases: Use
scripts/run_collection_pipeline.py
to run plan / dispatch / summary three phases for image set path, agent sends 3 Bash commands in sequence; concurrency is completed by skill layer dispatch using
ThreadPoolExecutor
, agent itself does not run concurrently:
--phase plan
writes
image-plan.json
/
collection-state.json
, stdout directly outputs markdown table + 1 line of status JSON (including
specs[]
/
run_one_task_script
/
state_file
/
total
)
After user confirmation, agent only sends 1 dispatch Bash:
python <root of this skill>/scripts/run_collection_pipeline.py --phase dispatch --state <state_file>
; dispatch internally uses
ThreadPoolExecutor
to run
run_one_task.py --index 1..N
concurrently, each subtask outputs
task-result-<id>.json
fragment; dispatch itself does not emit
Saved full response
in stdout, only 1 line
{"status":"dispatch_complete",...}
at the end for agent internal parsing (this Bash does not render images, it is normal)
--phase summary --state <state_file>
reads fragments → stdout outputs final markdown details (each successful image comes with
![label](abs_path)
inline reference, front-end markdown renderer renders the entire set of images based on this) + 1 line of status JSON; meanwhile, it merges and writes
collection-asset-manifest.json
Prohibit Agent from manually executing S1 or reading full text of S0~S3; prohibit splitting into N Bash commands to run
run_one_task.py
after user confirmation (old protocol; concurrency is now completed at skill layer, self-concurrency will only result in duplicate images); prohibit stripping
![]()
lines when forwarding summary markdown (the entire set of images relies on these lines for rendering); prohibit attaching
Saved full response: [...]
outside summary (double rendering with markdown
![]()
). The following bash single-step link only applies to single-image direct generation.
Path Iron Rule: This link spans two skill directories (parameter construction scripts belong to this skill, text generation and parameter annotation scripts belong to
linkfox-aigc-textgen
), the current working directory is not fixed, all scripts must be called with absolute paths, do not use bare
scripts/...
relative paths (relative paths will point to wrong directories and cause execution failure). Where
<root of this skill>
= absolute path of the directory where this SKILL.md is located;
<textgen root directory>
is obtained by parsing the absolute path of the directory where its SKILL.md is located via
skill:linkfox-aigc-textgen
.
Parameter Construction (this skill):
python <root of this skill>/scripts/build_textgen_params.py --type <TYPE> ... --out <textgen_params.json>
Text Generation (textgen skill):
PROMPT=$(python <textgen root directory>/scripts/aigc_textgen.py --stdin --content-only < <textgen_params.json>)
——
--content-only
outputs single-line content captured into variable (line breaks are flattened to
⏎
, downstream automatic restoration mechanism see textgen SKILL.md).
Parameter Annotation (step 3, inline with
jq
): Use
jq
to inline
$PROMPT
into downstream imagegen parameter JSON, then pass to
linkfox-aigc-imagegen
for image generation.
bash
PROMPT=$(python <textgen root directory>/scripts/aigc_textgen.py --stdin --content-only < <textgen_params.json>)
PARAMS=$(jq -nc --arg p "$PROMPT" --argjson imgs '<URL JSON array from step 1>' \
  '{prompt:$p, imageUrls:$imgs, provider:"<provider>", outputNum:1, aspectRatio:"<ratio>", resolution:"<resolution>"}')
# Then pass $PARAMS to image generation according to the calling method in linkfox-aigc-imagegen SKILL.md
Prohibit manually constructing textgen parameter files with Write tool (must use
build_textgen_params.py
), extracting original content with
jq -r
(will reintroduce real line breaks and break splicing), or directly writing Python to call API to bypass this link.

Step 3: Call

linkfox-aigc-imagegen

for Image Generation (Universal for All Types)

Input:
```
prompt
```
from step 2,
```
imageUrls
```
from step 1,
```
ratio
```
,
```
resolution
```
,
```
provider
```
Operation: Read SKILL.md of
skill:linkfox-aigc-imagegen
and execute image generation script according to its calling method. Pass parameters:
- ```
prompt
```
  : Final prompt produced in step 2
- ```
imageUrls
```
  : All image URLs from step 1
- ```
provider
```
  : Model specified by input parameters (default
```
BANANA_PRO
```
  )
- ```
aspectRatio
```
  : Pass
```
ratio
```
  as is
- ```
resolution
```
  : Pass as is
- ```
outputNum
```
  :
```
1
```
Output: Image (local path after
```
Saved full response:
```
)
Single-image Direct Generation Delivery (By Type): For single-image direct generation scenario of this skill, follow §3.1 of
```
references/runtime/03-deliver.md
```
. After imagegen Bash is completed, agent must:
1. Parse
  Saved full response: ["..."]
  in stdout to get local path (1 image when successful)
2. Append markdown inline block to the conversation reply body:
  markdown
```
- Image 1 · <Chinese name of type>
  ![<Chinese name of type>](<abs_path>)
```
3. Chinese Name Mapping: SCENE→Scene Image / CLOSE_UP→Close-up Image / SELLING_POINT→Selling Point Image / WHITE_BG→White Background Image / PREMIUM_APLUS→Premium A+ Image / STANDARD_APLUS→Standard A+ Image / PHONE_APLUS→Mobile A+ Image
4. Prohibit repeating the protocol text
  Saved full response: [...]
  /
  Saved full response: <json path>
  into conversation reply — it is an internal protocol line between skill ↔ bridge, repeating it will let users see exposed JSON array paths (i.e., "protocol line exposure" fault); only read it to get the path, do not copy the literal
5. Prohibit manually echoing
  Saved full response:
  literal to let bridge render again — bridge path A's "task output" resource card is automatically triggered by imagegen Bash stdout, agent should not copy manually
6. Double rendering (markdown inline image + bridge "task output" resource card displayed simultaneously) is expected behavior under current protocol, not a fault
7. For failure cases (stdout is
  Saved full response: <data path>.json
  single file), truthfully inform according to "Error Handling and Failure Guards" in this SKILL.md, do not append inline image

Intermediate Product Storage (Mandatory)

All files to be reused across steps or delivered must be stored in the session directory

<cwd>/linkfox/<YYYY-MM-DD>/<session>/{data|media}/

(protocol see "Output File Location" in repository

CLAUDE.md

Product Type	Directory	Acquisition Method
Brand Gene JSON	`data/`	`save_brand_gene.py` of `linkfox-aigc-imagegen-brand-gene-extract`
Image Set Plan image-plan.json	`data/`	Append and store item by item via `scripts/save_image_plan.py` after S2 confirmation
imageUrls Array	`data/`	Write to `$DATADIR/image-urls.json` after step 1 verification (usually small)
task-result-*.json	`data/`	Task result fragment stored after each `run_one_task.py` is completed, read and summarized into final markdown + asset manifest in summary phase
collection-asset-manifest.json	`data/`	Automatically merge `assets[]` from task-result fragments and write in summary phase, record `src` , `slot` , `type` , `label` of each result image, for Listing HTML merge and re-rendering
Single-image Parameter Construction JSON (textgen/imagegen input parameters)	`data/`	`--out` of `build_textgen_params.py` / `build_imagegen_prompt.py` (only for single-image direct generation scenario)
Result Images	`media/`	Automatically stored by `linkfox-aigc-imagegen` script

DATADIR=$(python <brand-gene root directory>/scripts/save_brand_gene.py --datadir)

; downstream

--brand-gene-file

points to the absolute path of brand gene stored in S1.

Downstream Skill Calling Convention

This skill relies on the two downstream skills in the table below, call according to documented methods: first Read the other party's SKILL.md to understand their calling method, single-image direct generation follows the chain commands in steps 2/3, image set follows

scripts/run_collection_pipeline.py

scripts/run_one_task.py

orchestration — both call downstream official scripts with absolute paths as documented (this is allowed). This skill's own

build_textgen_params.py

build_imagegen_prompt.py

run_collection_pipeline.py

run_one_task.py

etc. are parameter construction and orchestration auxiliary scripts, which can be run directly. It is not allowed to splice calls on your own outside the above documented link, or directly connect to downstream HTTP APIs.

Downstream Skill	Purpose	Calling Timing
`linkfox-aigc-imagegen`	AI Image Generation	Step 3 (all types)
`linkfox-aigc-textgen`	Prompt Rewriting	Step 2 (all types except white background image)

Calling Method: Read SKILL.md of

skill:<skill-name>

and execute according to its calling method section.

Shared Input Parameters

The following parameters are universal for all types (type-specific parameters see each type reference):

Parameter	Type	Default	Description
`imageUrls`	string[]	Required	Product reference image URLs. Step 1 will verify accessibility
`ratio`	string	Varies by type	Image ratio, passed directly to `aspectRatio` of imagegen
`resolution`	string	2K	Resolution, 2K / 4K
`provider`	string	—	Image generation model ( `BANANA_PRO` / `GPT_2_IMAGE` / `BANANA_2` / `AIDRAW_EDIT` / `WAN2_7` ); if not passed, use `AskUserQuestion` to let user select from the above 5 models

Error Handling and Failure Guards

linkfox-aigc-imagegen
skill returns exit 0 for business failures (non-zero exit is not used), so cannot judge success or failure by command exit code, must parse stdout.

1. How to Judge Success or Failure of a Call

Success: stdout contains
```
Saved full response: ["xxx.png", ...]
```
(JSON array path) → Image has been stored in media/, get the path to display.
Failure: stdout contains
```
Saved full response: xxx.json
```
(single JSON file path, non-array) → No image product, need to read the JSON to view error details (
```
errcode
```
/
```
errmsg
```
/
```
error
```
).

2. How to Handle Failures (By Failure Type)

Failure Type	Judgment Basis	Handling
Invalid Parameters	`errmsg` / `errorMsg` points to input parameters such as `provider` , `aspectRatio` , `resolution` , `quality` not being accepted	Use `AskUserQuestion` to let user reselect corresponding parameters
Authentication Failure	`errcode==401` or prompt for API Key	Stop and prompt user to configure `LINKFOX_AGENT_API_KEY` , do not retry
Transient Error	`error` is network/timeout/connection failure ( `Connection failed` , timeout, etc.)	Automatically retry at most 1 time; if failed again, switch to "Other Errors"
Other Errors	Quota exceeded, content rejected, server 5xx, unknown errcode, etc.	Do not retry, truthfully inform user of failure reason

3. Hard Guards (Violation is Considered a Fault)

❌ Prohibit calling any other skill due to image generation failure — this skill has only one image generation path (
```
linkfox-aigc-imagegen
```
), handle or report according to the above table when failed, never "try another skill".
❌ Prohibit unlimited retries: Except "transient error at most 1 time", do not retry the same type of failure repeatedly.
❌ Prohibit treating failed return body as success and continue (display empty image, tell user "generated successfully").

Global Rules

Model Type Rules

This skill supports the following 5 image generation models, models are passed in by agent layer via

provider

parameter; if not passed in, this skill will confirm with the user.

Model Name	Internal Code
LFBanana Pro	`BANANA_PRO`
Img2	`GPT_2_IMAGE`
LFBanana2	`BANANA_2`
Linkfox-Image-1	`AIDRAW_EDIT`
Wan 2.7	`WAN2_7`

Model Confirmation: If

provider

is empty or not in the above table, use

AskUserQuestion

to let user select from the above 5 models, continue execution after user selection. Distribute

provider

uniformly to step 3.

Resolution Rules

Resolution is a mandatory parameter for step 3. This skill supports 2K, 4K.

Agent layer passed
```
resolution
```
(value is 2K or 4K): use directly
Agent layer did not pass: use
```
AskUserQuestion
```
to let user select from 2K / 4K

Task Independence Statement

Each image in the image set is an independent task, and tasks do not depend on each other. Failure of image generation for a single type does not affect the continued execution of other tasks.

Execution Constraints

No Upload Link: Product images are directly passed in the form of
```
imageUrls
```
, this skill does not involve local file upload operations (except URL verification in step 1), prohibit probing or calling any upload scripts.
Planning Tool Usage Specification: Do not use planning tools for single-image direct generation. Must create task plans for N images before concurrent image generation for image sets (see
```
references/runtime/02-confirm.md
```
).
Image Set Storage: plan / summary are written to disk by
```
run_collection_pipeline.py
```
; prohibit Agent from writing the entire manifest / image-plan from memory via Write.
Listing Report Write-back Asset Manifest (Mandatory): Retain
```
$DATADIR/collection-asset-manifest.json
```
after image set summary is completed. Listing HTML merge only uses
```
agent-listing-result-html-skill/scripts/merge-listing-assets.mjs
```
. If the manifest still contains local
```
media/
```
paths, the caller must first use
```
linkfox-file-upload
```
to replace them with public OSS URLs and update the manifest, then execute merge; this skill does not upload directly, but must not imply that local paths can be directly written into HTML.

Image Set Orchestration Process (runtime, Progressive Read)

Only triggered by image set path; do not read this section for single-image direct generation.

Step	Read	Operation
Entry	`references/runtime/00-index.md`	S0 scenario judgment
plan	`references/runtime/01-plan.md`	Write job.json → `--phase plan` , forward stdout markdown table as is + AskUserQuestion
Confirm → Dispatch → Summary	`references/runtime/02-confirm.md`	User confirmation → agent sends 1 `--phase dispatch` Bash (skill layer runs all `run_one_task.py` concurrently, does not render images) → immediately send 1 `--phase summary` Bash to write manifest + output markdown details containing `![]()`

Maintenance details see

references/maintainer/collection/

, prohibit reading during runtime.

Known Limitations

White background image template is static instruction, no category recognition and structure judgment, all categories are uniformly processed as "background removal + retouching + centered enlargement"; edge processing of special-shaped / transparent / reflective products may not meet expectations.
Scene images/close-up images strongly rely on category and structure judgment of
```
linkfox-aigc-textgen
```
(
```
GEM_3_FLASH
```
), judgment errors will directly affect composition.
Selling point images/A+ images share dictionary templates, distinguished by
```
{layoutInfo}
```
; wrong intent filling will lead to layout mismatch.
Template text is written in apparel category tone ("fabric texture / version advantage"), adapted by model when used for non-apparel products.
When multiple reference images are provided, the model judges the subject by itself, which may lead to misjudgment in complex combinations.
No sensitive word rewriting (scene images/close-up images/white background images): if selling points/scenes contain prohibited content, this link does not intercept, controlled by upstream or manual review. Selling point images/A+ images include sensitive word avoidance in textgen phase.

Resolve Authentication and Credit Issues

When the following abnormal situations occur, guide users to solve problems using references/onboarding.md:

Abnormal Situations

API Key Not Configured: Environment variable
```
LINKFOX_AGENT_API_KEY
```
is not configured, nor is
```
LINKFOXAGENT_API_KEY
```
.
Response Returns 401 or 402 Status Code
Response Indicates Insufficient Credits or Balance: Message contains "insufficient credit balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/need recharge/please recharge", or similar meanings.

linkfox-aigc-imagegen-product

NPX Install

Tags

SKILL.md Content (Chinese)