linkfox-aigc-imagegen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI 生图

AI Image Generation

根据提示词和参考图生成图片，支持多种 AI 模型，异步创建任务后轮询获取结果。

Generate images based on prompts and reference images, supporting multiple AI models. Create tasks asynchronously and poll for results.

核心特点

Core Features

多模型选择：7 种模型可选，各有不同特长和分辨率支持。
图生图：可传入参考图+提示词生成新图。
批量输出：单次最多生成 10 张图片。
异步模式：创建任务立即返回 taskId，脚本自动轮询直到完成（超时 10 分钟）。

Multiple Model Options: 7 models available, each with unique strengths and resolution support.
Image-to-Image: Generate new images by passing reference images + prompts.
Batch Output: Generate up to 10 images in one go.
Asynchronous Mode: Immediately return a taskId after creating a task, and the script automatically polls until completion (timeout after 10 minutes).

模型说明

Model Description

模型（provider）	说明	特点
BANANA	LFBanana（基础版）	仅支持 1K 分辨率
BANANA_2	LFBanana2	支持更高分辨率
BANANA_PRO	LFBanana Pro（默认）	综合效果最好
GPT_2_IMAGE	Img2	支持 quality 参数控制质量
AIDRAW_EDIT	Linkfox-Image-1	适合编辑类场景
WAN2_7	Wan 2.7	万相模型
SEEDREAM5	Seedream 5.0	仅支持2K

Model (provider)	Description	Features
BANANA	LFBanana (Basic Version)	Only supports 1K resolution
BANANA_2	LFBanana2	Supports higher resolution
BANANA_PRO	LFBanana Pro (Default)	Best comprehensive performance
GPT_2_IMAGE	Img2	Supports quality parameter to control output quality
AIDRAW_EDIT	Linkfox-Image-1	Suitable for editing scenarios
WAN2_7	Wan 2.7	Wanxiang Model
SEEDREAM5	Seedream 5.0	Only supports 2K

参数概览

Parameter Overview

必填字段：
```
prompt
```
、
```
imageUrls
```
、
```
outputNum
```
（默认
```
1
```
）、
```
resolution
```
（默认
```
1K
```
）、
```
quality
```
（默认
```
high
```
，仅 GPT_2_IMAGE）

完整参数表、响应字段结构与错误码，见

references/api.md

。

Required Fields:
```
prompt
```
,
```
imageUrls
```
,
```
outputNum
```
(default
```
1
```
),
```
resolution
```
(default
```
1K
```
),
```
quality
```
(default
```
high
```
, only for GPT_2_IMAGE)

Complete parameter table, response field structure and error codes can be found in

references/api.md

调用方式

Calling Methods

创建任务：
```
POST /aigc/imageGenAsync
```
→ 返回
```
{taskId}
```
轮询结果：
```
POST /aigc/taskQuery
```
→ 传入
```
{taskId}
```
→ 返回状态和结果
Python 脚本：
```
python scripts/aigc_imagegen.py '<JSON 参数>'
```
（脚本内部自动完成创建+轮询）

异步流程：

脚本调用
```
/aigc/imageGenAsync
```
创建任务，获得
```
taskId
```
轮询
```
/aigc/taskQuery
```
，初始间隔 10 秒，每次递减 1 秒至最低 5 秒，最长等待 10 分钟
成功后自动下载图片到会话
```
media/
```
目录

文件存储路径约定（遵循 CLAUDE.md 规范）：

所有文件存储在

<cwd>/linkfox/<YYYY-MM-DD>/<session>/

下，按类型划分目录：

内容类型	目录	路径格式	说明
生成的图片	`media/`	`<session>/media/linkfox-aigc-imagegen-<ts_ms>.<ext>`	如 `media/linkfox-aigc-imagegen-1718000000000.png`
原始 API 响应	`data/`	`<session>/data/linkfox-aigc-imagegen-<ts>.json`	含完整 taskId、状态、临时 URL 等

输出策略（脚本默认行为）：

成功生成图片时（无论多少张）：
- stdout 输出
```
Saved full response: <路径数组>
```
  格式的行，例如：
  - 1张：
```
Saved full response: ["/path/to/media/a.png"]
```
  - 多张：
```
Saved full response: ["/path/to/media/a.png", "/path/to/media/b.png"]
```
- 原始 API 响应（含临时 URL 等）静默落盘到
```
data/
```
  。
- 前端 UI 可解析 stdout 中所有
```
Saved full response:
```
  行，把后续 JSON 数组渲染出来。
- 每次调用脚本通常输出一行；分多次调用时会有多行。
无图片产物时（失败/无结果）：
- stdout 输出原始响应路径：
```
Saved full response: /path/to/data/xxx.json
```

读数据建议：禁止 Read 转存的图片文件内容（避免 base64 进入上下文）。直接把

Saved full response:

后的本地路径提供给用户即可。

Create Task:
```
POST /aigc/imageGenAsync
```
→ Returns
```
{taskId}
```
Poll for Results:
```
POST /aigc/taskQuery
```
→ Pass
```
{taskId}
```
→ Returns status and results
Python Script:
```
python scripts/aigc_imagegen.py '<JSON Parameters>'
```
(The script automatically handles task creation + polling internally)

Asynchronous Process:

The script calls
```
/aigc/imageGenAsync
```
to create a task and obtain
```
taskId
```
Poll
```
/aigc/taskQuery
```
, initial interval is 10 seconds, decrease by 1 second each time to a minimum of 5 seconds, maximum waiting time is 10 minutes
Automatically download images to the session
```
media/
```
directory after success

File Storage Path Convention (follows CLAUDE.md specification):

All files are stored under

<cwd>/linkfox/<YYYY-MM-DD>/<session>/

, organized by type into directories:

Content Type	Directory	Path Format	Description
Generated Images	`media/`	`<session>/media/linkfox-aigc-imagegen-<ts_ms>.<ext>`	e.g., `media/linkfox-aigc-imagegen-1718000000000.png`
Original API Response	`data/`	`<session>/data/linkfox-aigc-imagegen-<ts>.json`	Contains complete taskId, status, temporary URL, etc.

Output Strategy (Default Script Behavior):

When images are successfully generated (regardless of quantity):
- Output lines in the format
```
Saved full response: <path array>
```
  to stdout, for example:
  - 1 image:
```
Saved full response: ["/path/to/media/a.png"]
```
  - Multiple images:
```
Saved full response: ["/path/to/media/a.png", "/path/to/media/b.png"]
```
- The original API response (including temporary URL, etc.) is silently saved to the
```
data/
```
  directory.
- The front-end UI can parse all
```
Saved full response:
```
  lines in stdout and render the subsequent JSON array.
- Usually outputs one line per script call; multiple lines will be generated for multiple calls.
When no image output is produced (failure/no results):
- Output the original response path to stdout:
```
Saved full response: /path/to/data/xxx.json
```

Data Reading Recommendation: Prohibited to read the content of transferred image files (to avoid base64 entering the context). Directly provide the local path after

Saved full response:

to users.

解决认证和积分问题

Resolve Authentication and Point Issues

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

When the following exceptions occur, guide users to solve them using references/onboarding.md:

异常情况

Exception Scenarios

未配置API Key：环境变量未配置
```
LINKFOX_AGENT_API_KEY
```
，也未配置
```
LINKFOXAGENT_API_KEY
```
。
响应401或402状态码
响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

API Key Not Configured: Neither
```
LINKFOX_AGENT_API_KEY
```
nor
```
LINKFOXAGENT_API_KEY
```
is configured in environment variables.
Response returns 401 or 402 status code
Response indicates insufficient points or balance: Messages contain phrases like "insufficient points balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/need to recharge/please recharge" or similar meanings.

使用指引

Usage Guide

模型选择：一般场景用
```
BANANA_PRO
```
（默认）；需要高质量画质控制用
```
GPT_2_IMAGE
```
；编辑现有图片用
```
AIDRAW_EDIT
```
。
提示词：描述越具体效果越好，建议用英文提示词获得更好效果。
参考图：必须提供至少一张参考图 URL。
分辨率：支持 1K/2K/4K，默认 1K。

Model Selection: Use
```
BANANA_PRO
```
(default) for general scenarios; use
```
GPT_2_IMAGE
```
for high-quality image control; use
```
AIDRAW_EDIT
```
for editing existing images.
Prompts: The more specific the description, the better the effect. It is recommended to use English prompts for better results.
Reference Images: At least one reference image URL must be provided.
Resolution: Supports 1K/2K/4K, default is 1K.

示例

Examples

1. 用默认模型生成商品场景图

json

{"imageUrls": ["https://example.com/product.jpg"], "prompt": "product photography on white background, studio lighting", "provider": "BANANA_PRO", "outputNum": 1, "resolution": "1K", "aspectRatio": "1:1", "quality": "high"}

2. 用 GPT_2_IMAGE 高质量生图

json

{"imageUrls": ["https://example.com/ref.jpg"], "prompt": "modern minimalist product showcase", "provider": "GPT_2_IMAGE", "outputNum": 1, "resolution": "1K", "aspectRatio": "16:9", "quality": "high"}

3. 批量生成多张

json

{"imageUrls": ["https://example.com/ref.jpg"], "prompt": "creative product ad design", "provider": "BANANA_PRO", "outputNum": 4, "resolution": "2K", "aspectRatio": "1:1", "quality": "high"}

1. Generate Product Scene Image with Default Model

json

{"imageUrls": ["https://example.com/product.jpg"], "prompt": "product photography on white background, studio lighting", "provider": "BANANA_PRO", "outputNum": 1, "resolution": "1K", "aspectRatio": "1:1", "quality": "high"}

2. Generate High-Quality Image with GPT_2_IMAGE

json

{"imageUrls": ["https://example.com/ref.jpg"], "prompt": "modern minimalist product showcase", "provider": "GPT_2_IMAGE", "outputNum": 1, "resolution": "1K", "aspectRatio": "16:9", "quality": "high"}

3. Batch Generate Multiple Images

json

{"imageUrls": ["https://example.com/ref.jpg"], "prompt": "creative product ad design", "provider": "BANANA_PRO", "outputNum": 4, "resolution": "2K", "aspectRatio": "1:1", "quality": "high"}

限制

Limitations

必须提供至少一张参考图 URL。
单次最多生成 10 张。
生成时间视模型和分辨率不同，通常 10-120 秒。脚本自动轮询，超时 10 分钟。
失败时不重试（仅尝试 1 次）。

At least one reference image URL must be provided.
Maximum 10 images can be generated per request.
Generation time varies by model and resolution, usually 10-120 seconds. The script automatically polls, with a timeout of 10 minutes.
No retries on failure (only one attempt).

不适用

Not Applicable Scenarios

不适用：

纯文字生成 →
```
linkfox-aigc-textgen
```
视频生成 →
```
linkfox-aigc-videogen
```

Not applicable for:

Pure text generation →
```
linkfox-aigc-textgen
```
Video generation →
```
linkfox-aigc-videogen
```

反馈

Feedback

参见

references/api.md

。

Refer to

references/api.md

执行指令

Execution Instructions

重要：收到本文档末尾的

ARGUMENTS:

字段后，必须立即调用

python scripts/aigc_imagegen.py '<JSON>'

执行，禁止等待用户确认或额外输入。

Important: After receiving the

ARGUMENTS:

field at the end of this document, you must immediately execute

python scripts/aigc_imagegen.py '<JSON>'

, do not wait for user confirmation or additional input.