SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-aigc-imagegen-product

linkfox-aigc-imagegen-product

Design & creation

View repository

Updated 10-15 23:40

About this skill

Product Image Generation

Unified entry point: full-type e-commerce image generation capability for non-apparel products (beauty, digital, home, food, etc.). Both single-image direct generation & image-set orchestration are entered from this one skill.

Entry Routing

Condition Path Action
Only one image of a specific type (e.g. "make a white-background image") Single-image direct generation Determine type → Read corresponding references/types/<type>.md → execute shared pipeline
Multiple images / multiple types / image set (e.g. "make an image set", "produce 5 images") Image-set orchestration Read references/runtime/00-index.md → Read step by step 01-plan / 02-confirm → call scripts/run_collection_pipeline.py three stages(plan / dispatch / summary, the agent sequentially issues 3 Bash commands; dispatch runs concurrently at the skill layer with ThreadPoolExecutor concurrent runs of scripts/run_one_task.py, the agent itselfdoes notrun concurrently;prohibited Read maintainer/collection/ or Read during the image-set stage types/*.md）

Type Routing Table

type Name Associated with selling points Has scene description Default ratio Detail 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 Advanced 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 determining the type,you must Read the corresponding type reference file to obtain that type's step 2 differential logic and prompt template,skipping is prohibited。

Not applicable

  • Apparel / model-type images (tops/bottoms/dresses/outerwear/shoes and hats, etc.) → go through the linkfox-aigc-imagegen-cloth series.
  • Pure image editing operations (background replacement, watermark removal, angle change, and other operations with an already clear creative direction) → go through linkfox-aigc-imagegen。
  • Pure text generation → linkfox-aigc-textgen。
  • Video generation → linkfox-aigc-videogen。

Shared Pipeline

All types go through the same 3-step pipeline; the differential parts are defined by each type reference.

Step 1: Validate image URL accessibility (common to all types)

  • Input：imageUrls
  • Empty-array guardrail (mandatory): if imageUrls is an empty array / missing / all invalid,stop immediately, do not call downstream with empty images. First fill in from context (the original image paths uploaded by the user in this round/history); if it still cannot be filled in, truthfully report the error to the user and request re-upload,Prohibitedwith empty imageUrls continue execution.
  • Operation: check each item in imageUrls (keep the original order): if it is already a public URL (starting with http/https) → pass it through directly; if it is a local file path (not http/https) → call linkfox-file-upload to upload and obtain a public URL, then replace it.
  • Output：imageUrls(all are publicly accessible HTTPS URLs)

Step 2: construct the final prompt (see each type reference for the differences)

The step 2 logic differs by type (whether to call textgen, which model to use, whether to do sensitive-word evasion, etc.); see the already-Read references/types/<type>.md。

White background image static direct output 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 body text from the references/types/white-bg.md of text code block as the final prompt. The body text is long, so always have the script read it,do not manually copy it or pass it through shell variables。

textgen chained call constraint (applies to all types except white background image): for any type that needs to call linkfox-aigc-textgen , you must use this skill's build_textgen_params.py helper script to build the textgen parameter file (the script automatically completes template reading, placeholder filling, model/thinkingLevel settings, and appending sensitive-word evasion instructions), then follow the textgen SKILL.md'schained call methodto execute.

Image set must go through the pipeline's three stages: for the image set path, use scripts/run_collection_pipeline.py to run the three stages plan / dispatch / summary; the agent sends 3 Bash commands in order; concurrency is handled by the skill-layer dispatch using ThreadPoolExecutor ,the agent itself does not run concurrently：

  1. --phase plan writes image-plan.json / collection-state.json, stdout directly prints a markdown table + 1 line of status JSON (including specs[] / run_one_task_script / state_file / total）
  2. After user confirmation, the agent sends only 1 dispatch Bash:python <本skill根>/scripts/run_collection_pipeline.py --phase dispatch --state <state_file>; inside dispatch, use ThreadPoolExecutor to run concurrently run_one_task.py --index 1..N, each subtask writes a task-result-<id>.json fragment; dispatch's own stdout does not emit Saved full response, only the last 1 line of {"status":"dispatch_complete",...} for the agent to parse internally (this Bash does not render images, which is normal)
  3. --phase summary --state <state_file> reads the fragments → stdout prints the final markdown details (each successful image comes with ![label](abs_path) inline reference, and the frontend markdown renderer renders the whole image set based on this) + 1 line of status JSON; at the same time, merge and write collection-asset-manifest.json

Prohibited Agent manually S1 or Read the full text of S0~S3;Prohibitedafter user confirmation, split N Bash commands yourself to run run_one_task.py(old protocol; concurrency is now done at the skill layer, running concurrently yourself will only duplicate image generation);Prohibitedwhen forwarding the summary markdown, strip out the ![]() lines (the whole image set relies on these lines for rendering);Prohibitedto paste Saved full response: [...]outside of summary (double rendering with markdown ![]() ). The bash single-step chain belowonly applies to single-image direct output。

Path iron rule: this chain spans two skill directories (the parameter-building script belongs to this skill, the text-generation and parameter-injection scripts belong to linkfox-aigc-textgen), the current working directory is not fixed,All scripts must be invoked with absolute paths, do not use bare scripts/... relative paths(relative paths will point to the wrong directory and cause execution failure). Where <本skill根目录> = the absolute path of the directory containing this SKILL.md;<textgen根目录> is obtained by skill:linkfox-aigc-textgen resolving the absolute path of the directory containing its SKILL.md.

  1. Param construction (this skill):python <本skill根目录>/scripts/build_textgen_params.py --type <TYPE> ... --out <textgen_params.json>
  2. Text generation (textgen skill):PROMPT=$(python <textgen根目录>/scripts/aigc_textgen.py --stdin --content-only < <textgen_params.json>) —— --content-only output a single-line content captured into a variable (newlines flattened to ⏎, the mechanism for automatic downstream restoration is described in textgen SKILL.md).
  3. Param injection (step 3, using jq inline): use jq to inline-splice $PROMPT into the downstream imagegen parameter JSON, then hand it to linkfox-aigc-imagegen to generate the image. 
    PROMPT=$(python <textgen根目录>/scripts/aigc_textgen.py --stdin --content-only < <textgen_params.json>)
PARAMS=$(jq -nc --arg p "$PROMPT" --argjson imgs '<步骤1的URL JSON数组>' \
  '{prompt:$p, imageUrls:$imgs, provider:"<provider>", outputNum:1, aspectRatio:"<ratio>", resolution:"<resolution>"}')
# 然后按 linkfox-aigc-imagegen SKILL.md 的调用方式把 $PARAMS 传入出图

Prohibitedmanually constructing the textgen parameter file with the Write tool (must go through build_textgen_params.py), using jq -r to extract the raw content (which would reintroduce real newline characters and break the splicing), or directly writing Python to call the API and bypass this chain.

Step 3: call linkfox-aigc-imagegen to generate the image (common to all types)

  • Input: from step 2, prompt, from step 1, imageUrls、ratio、resolution、provider
  • Operation：Read skill:linkfox-aigc-imagegen 's SKILL.md, execute the image generation script according to its invocation method. Parameters passed in:
    • prompt: the final prompt produced in step 2
    • imageUrls: all image URLs from step 1
    • provider: the model specified by the input parameters (default BANANA_PRO）
    • aspectRatio：ratio passed through as-is
    • resolution: passed through as-is
    • outputNum：1
  • Output: image (the local path afterSaved full response: )
  • Single-image direct delivery (by type): for this skill's single-image direct delivery scenario, follow references/runtime/03-deliver.md §3.1; after the imagegen Bash completes, the agent must:

    1. parse stdout's Saved full response: ["..."] to get the local path (1 image on success)

    2. in the conversation reply body,append a markdown inline block:

      - 第 1 张 · <类型中文名>
  ![<类型中文名>](<abs_path>)

    3. Type 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. Prohibitedto repeat the Saved full response: [...] / Saved full response: <json路径> protocol text verbatim into the conversation reply—it is an internal skill ↔ bridge protocol line, and repeating it would let the user see a bare JSON array path (i.e., the "protocol line exposure" fault); only read it to get the path, do not copy the literal text

    5. Prohibitedto echo Saved full response: literally yourself to make the bridge render it again—the bridge path A's "task output" resource card is automatically triggered by imagegen Bash stdout, the agent should not manually copy it

    6. Double rendering(markdown inline image + bridge "task output" resource card presented simultaneously) is expected behavior under the current protocol and is not a fault

    7. Failure case (stdout is Saved full response: <data 路径>.json single file): report truthfully according to this SKILL.md's "Error Handling and Failure Guardrails", do not append an inline image

Intermediate artifacts persisted to disk (mandatory)

All files that need to be reused across steps or delivered must be written to the session directory <cwd>/linkfox/<YYYY-MM-DD>/<session>/{data|media}/(protocol see repository CLAUDE.md"output file location").

Artifact type Directory How obtained
Brand DNA JSON data/ linkfox-aigc-imagegen-brand-gene-extract of save_brand_gene.py
image set plan image-plan.json data/ After S2 confirmation scripts/save_image_plan.py append each entry to disk
imageUrls array data/ After step 1 validation, Write to $DATADIR/image-urls.json(usually very small)
task-result-*.json data/ each run_one_task.py task result fragment after completion is written to disk; the summary phase reads them and aggregates the final markdown + asset manifest
collection-asset-manifest.json data/ the summary phase automatically merges from the task-result fragments assets[] writes out, recording each result image's src、slot、type、label, for Listing HTML merge re-rendering
Single-image construction parameter JSON (textgen/imagegen input) data/ build_textgen_params.py / build_imagegen_prompt.py of --out(only for single-image direct output scenarios)
Result image media/ linkfox-aigc-imagegen script automatically writes to disk

DATADIR=$(python <brand-gene根目录>/scripts/save_brand_gene.py --datadir); downstream --brand-gene-file points to the absolute path of the brand DNA written to disk by S1.

Downstream skill invocation conventions

This skill depends on the two downstream skills in the table below,invoked in the documented manner: first Read the other party's SKILL.md to understand its invocation method; for single-image direct output, follow the chained commands in steps 2/3; for image sets, follow scripts/run_collection_pipeline.py + scripts/run_one_task.py orchestration—both invoke the downstream official scripts viaabsolute pathas documented (this is allowed). This skill's built-in build_textgen_params.py / build_imagegen_prompt.py / run_collection_pipeline.py / run_one_task.py etc. are parameter construction and orchestration helper scripts and can be run directly. Assembling invocations on your own outside the above documented chains, or connecting directly to the downstream HTTP API, is what is not allowed.

Downstream skill Purpose Invocation timing
linkfox-aigc-imagegen AI image generation Step 3 (all types)
linkfox-aigc-textgen Prompt rewriting Step 2 (all types except white background images)

Invocation method: Read skill:<skill-name> 's SKILL.md, and execute according to its invocation method section.

Shared input parameters

The following parameters are common to all types (type-specific parameters are in each type reference):

Parameter Type Default Description
imageUrls string[] Required Product reference image URL. Step 1 validates accessibility
ratio string Depends on type Image aspect ratio, passed through as-is to imagegen's aspectRatio
resolution string 2K Resolution, 2K / 4K
provider string — Image generation model (BANANA_PRO / GPT_2_IMAGE / BANANA_2 / AIDRAW_EDIT / WAN2_7); when not provided, use AskUserQuestion to let the user choose from the above 5 models

Error handling and failure guardrails

linkfox-aigc-imagegen skill forbusiness failures also return exit 0(not a non-zero exit), soyou cannot judge success or failure by the command exit code; you must parse stdout。

1. How to judge the success or failure of a single invocation

  • Success: stdout contains Saved full response: ["xxx.png", ...](JSON array path) → the image has been written to media/; take the path for display.
  • Failure: stdout contains Saved full response: xxx.json(a single JSON file path, not an array) → no image artifact; you need to read that JSON to view the error details (errcode/errmsg/error）。

2. How to handle failures (route by type)

Failure type Basis for judgment Handling
Invalid parameters errmsg/errorMsg points to provider、aspectRatio、resolution、quality and other input parameters are not accepted Use AskUserQuestion to let the user reselect the corresponding parameter
Authentication failure errcode==401 or prompt for API Key Stop and prompt the 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 it fails again, switch to "Other errors"
Other errors Quota, content rejected, server-side 5xx, unknown errcode, etc. Do not retry, truthfully inform the user of the failure reason

3. Hard guardrails (violation is considered a fault)

  • ❌ It is forbidden to switch to any other skill due to image generation failure—this skill has only one image generation path (linkfox-aigc-imagegen); if it fails, handle it according to the table above or report it, and never "try another skill".
  • ❌ Unlimited retries are forbidden: except for "transient errors at most 1 time", the same type of failure must not be retried repeatedly.
  • ❌ It is forbidden to treat a failed response body as successand continue onward (displaying an empty image, telling the user "generated").

Global rules

Model type rules

This skill supports the following 5 image generation models, and the model is passed in by the agent layer through the provider parameter; if not passed in, this skill confirms 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 table above, use AskUserQuestion to let the user choose from the above 5 models, and continue execution after the user selects. Pass provider uniformly to step 3.

Resolution rules

Resolution is a required parameter for step 3. This skill supports 2K、4K。

  1. The agent layer passed through resolution(value is 2K or 4K): use directly
  2. The agent layer did not pass it through: use AskUserQuestion to let the user choose from 2K / 4K

Task independence statement

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

Execution-time constraints

  1. No upload step: product images are passed directly in the form of imageUrls , and this skill does not involve local file upload operations (except for the URL validation in step 1); it is forbidden to probe or call any upload script.
  2. Plan management tool usage specification: do not use the plan tool for single-image direct output. Before concurrent image set generation, a task plan must be created for N images (see references/runtime/02-confirm.md）。
  3. Image set persistence: plan / summary are written to disk by run_collection_pipeline.py ;Forbidden Agent writes the entire manifest / image-plan from memory.
  4. Listing report write-back asset list (mandatory): after the image set summary is completed, retain $DATADIR/collection-asset-manifest.json. Listing HTML merge only uses agent-listing-result-html-skill/scripts/merge-listing-assets.mjs. If the manifest still contains a local media/ path, the caller should first use linkfox-file-upload to replace it with a public OSS URL and update the manifest, then execute merge; this skill does not upload directly, but must not imply that a local path can be written directly into HTML.

Image set orchestration flow (runtime, progressive Read)

Triggered only by the image set path; for single-image direct output, do not Read this section.

Step Read Operation
Entry references/runtime/00-index.md S0 Scenario determination
plan references/runtime/01-plan.md Write job.json → --phase plan, forward the stdout markdown table as-is + AskUserQuestion
confirm → dispatch → summary references/runtime/02-confirm.md User confirms → agent sends 1 --phase dispatch Bash (skill layer runs all concurrently run_one_task.py, without rendering images) → immediately followed by 1 --phase summary Bash writes manifest + prints markdown details containing ![]() markdown details

For maintenance details, see references/maintainer/collection/，Read is prohibited at runtime。

Known limitations

  • The white background image template is static instructions, with no category recognition or structural determination; all categories are uniformly handled as "background removal + retouching + centered enlargement"; edge handling for irregular / transparent / reflective products may be less than expected.
  • Scene images/close-up images strongly depend on linkfox-aigc-textgen（GEM_3_FLASH) for category and structure determination; determination errors propagate directly to composition.
  • Selling point images/A+ share dictionary templates, distinguished by {layoutInfo} ; filling in the intent incorrectly will cause layout type crossover.
  • The template body text is written in the tone of the apparel category ("fabric texture / fit advantages"); when used for non-apparel products, the model adapts accordingly.
  • With multiple reference images, the model determines the subject on its own, and may misjudge under complex combinations.
  • No sensitive word rewriting is performed (scene images/close-up images/white background images): if selling points/scenes contain prohibited content, this pipeline does not intercept it, and it is left to upstream or manual review. Selling point images/A+ images include sensitive word avoidance in the textgen stage.

Resolve authentication and compute issues

When the following abnormal situations occur, use references/onboarding.md to guide problem resolution:

Abnormal situation

  • API Key not configured: environment variable not configured LINKFOX_AGENT_API_KEY, and also not configured LINKFOXAGENT_API_KEY。
  • Response 401 or 402 status code
  • Response indicates insufficient compute or balance: the message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with a similar meaning.