haizei-agnes-image-gen

Image Generation and Editing (Agnes Image 2.1 Flash)

An image generation skill implemented based on the Agnes Image 2.1 Flash model of the Agnes AI official API, which can help users generate images through natural language, requiring only a Node.js runtime environment. Both text-to-image and image-to-image (editing/multi-image fusion) transmit image data using Base64, with no third-party dependencies required. Agnes Image 2.1 Flash is an image generation model upgraded and released by Sapiens AI, optimized for high-information-density images, making it more suitable for scenarios such as complex visual details, rich compositions, dense elements, and clear semantic alignment.

Usage Guidelines

Follow these steps:

Step 1: Analyze Requirements and Extract Parameters

Clarify intent: Distinguish whether the user needs [text-to-image] (generating a new image), [image-to-image] (editing/modifying an existing image), or [multi-image fusion].
Prompt analysis：
- Use the user's original complete input: Directly use the user's original complete problem requirement description (original text) as the -p main body of the prompt, avoiding rewriting, summarizing, or secondary creation on your own to prevent loss of details.
- Confirm first when supplementation is needed: If the information is insufficient (for example, missing style, number of subjects, camera language, scene details, text content, prohibited elements, etc.), first ask the user to confirm; after the user confirms, then append the supplementary contentin an "append" mannerto the end of the original prompt.
- Example:
  - User input: "Help me generate an image of a cat, and make the style a bit cute."
  - Positive example explanation: Directly use the user input as the prompt:-p "帮我生成一张猫的图片，风格要可爱一点。"
  - Negative example explanation: Arbitrarily rewriting it as "Generate an image of a cute-style cat" will lose the details and tone of the user's original input.
  - If supplementary details are needed (for example, color, background, etc.), first ask and confirm: "What color do you want the cat to be? Are there any requirements for the background?" After the user answers, then append to the prompt:-p "帮我生成一张猫的图片，风格要可爱一点。猫是橘色的，背景是草地。"

Organize key parameters：
- Prompt (required): The final prompt after prompt analysis (default = the user's original complete and consistent input; supplementary information is appended only after user confirmation).
- Filename (optional): Output image filename/path (must include a random file identifier to avoid duplication). If not provided, the script will automatically generate a filename with a timestamp. It is recommended to generate a reasonable filename based on the content (for example, cat_in_garden.png), avoiding generic names.
- Size (required): Output size, format WIDTHxHEIGHT, for example, 1024x768、1536x1024、1024x1536、2048x2048. The model supports any valid custom size (recommended to refer to references/size-guide.md).
- Input Image (optional): Input image path(s) for image-to-image, and multiple images can be provided (up to 5). Passing this parameter enters editing/multi-image fusion mode; input images will automatically be converted to Data URI Base64 form for sending.

Step 2: Environment Check and Command Execution

Check environment: Confirm AGNES_API_KEY Whether the environment variable has been set (usually assumed to be set; if the run fails, prompt the user again).

Build and run the command：

Use Node.js version: call scripts/generate_image.js(zero dependencies, Node.js 18+ is sufficient).

Text-to-image command template:

node scripts/generate_image.js -p "{prompt}" -s "{size}" [-f "{filename}"]

Image-to-image command template:

node scripts/generate_image.js -p "{edit_instruction}" -s "{size}" -i "{input_path}" -f "{output_filename}"

Multi-image fusion command template:

node scripts/generate_image.js -p "融合图1和图2的风格" -s "{size}" -i ref1.png ref2.png -f "merged.png"

⏱️ Long-running task handling strategy

1. Pre-task notice

Before execution, you must inform the user：

"Image generation has started, it is expected to take 60 to 360 seconds, please wait patiently"

2. 🎨 Best practice example

"Image is being generated, expected to complete in 60-360 seconds...\n⏳ Generating...\n(High-information-density complex scenes may take longer, please wait patiently)"

Step 3: Result feedback

Execution feedback: wait for the terminal command to finish executing.
Success: inform the user that the image has been generated, and point out the save path and actual elapsed time.
Failure：
- If it indicates that the API Key is missing, guide the user to set the environment variable.
- If it indicates a network error or timeout, suggest that the user check the network or try again later.
- If it indicates a 400 error, refer to "Common Errors and Troubleshooting" at the end of SKILL.md.

Command-line usage examples

Generate a new image (text-to-image)

node scripts/generate_image.js -p "图片描述文本" -s "{size}" [-f "output.png"]

Example:

# 基础生成
node scripts/generate_image.js -p "A luminous floating city above a misty canyon at sunrise" -s "1024x768"

# 指定文件名
node scripts/generate_image.js -p "A clean product photo of a glass cube on a white studio background" -s "1024x768" -f "product.png"

# 竖版高清图片（适合手机壁纸）
node scripts/generate_image.js -p "未来城市夜景" -s "1024x1536" -f "city.png"

# 高信息密度场景
node scripts/generate_image.js -p "A futuristic city marketplace filled with flying vehicles, holographic signs, dense crowds, neon lighting, cinematic realism, ultra-detailed" -s "1536x1024" -f "city_market.png"

Edit an existing image (image-to-image)

node scripts/generate_image.js -p "编辑指令" -s "{size}" -i "path/to/input.png" [-f "output.png"]

Example:

# 修改风格
node scripts/generate_image.js -p "Convert the scene into a rain-soaked cyberpunk night with neon reflections while preserving the original composition" -s "1024x768" -i "original.png"

# 添加元素
node scripts/generate_image.js -p "Add a rainbow in the sky while preserving the original composition" -s "1024x768" -i "landscape.png" -f "rainbow.png"

# 替换背景
node scripts/generate_image.js -p "Replace the background with a beach while preserving the main subject" -s "1024x1024" -i "portrait.png" -f "beach_bg.png"

# 局部修改
node scripts/generate_image.js -p "Make the object orange while preserving the original composition" -s "1024x768" -i "photo.png" -f "orange.png"

# 多图融合（最多5张）
node scripts/generate_image.js -p "Blend the styles of image1 and image2" -s "1024x768" -i ref1.png ref2.png -f "merged.png"

Command-line parameter description

Parameter	Required	Description
`-p` / `--prompt`	Yes	Image description (text-to-image) or editing instruction (image-to-image). Preserve the user's original complete input.
`-s` / `--size`	Yes	Output size, format `WIDTHxHEIGHT`, for example `1024x768`、`1536x1024`。
`-f` / `--filename`	No	Output image path/filename; if not provided, a PNG filename with a timestamp is automatically generated.
`-i` / `--input-image`	No	Input image path for image-to-image; multiple images can be provided (up to 5). Passing this parameter enters editing mode.
`-k` / `--api-key`	No	API key (overrides the environment variable `AGNES_API_KEY`）。

File resource description

Resource	Description
`scripts/generate_image.js`	Node.js script (zero dependencies, available with Node.js 18+)
`references/size-guide.md`	Size and aspect ratio control documentation, use when needed, load on demand
`references/batch-template.md`	Batch generation configuration template, use when batch generation is needed, load on demand

Batch generation

When the user needs to generate multiple images at once (batch generation):

Load the configuration template：references/batch-template.md — includes JSON configuration format description and usage examples
Obtain/generate the JSON file: the user can provide the JSON file themselves, or describe the requirements and the AI generates it based on the requirements
Execute one by one: read the prompts array, execute the generation command one by one, and provide result feedback after each image is completed
Summary feedback: after completion, inform the user of the number of successes, the list of image paths, and the cumulative elapsed time

Note: total batch task time = single image time (60-360 seconds) × number of images. Please inform the user of the estimated duration in advance.

Prompt best practices

Agnes Image 2.1 Flash is particularly good at high-information-density scenarios. It is recommended to use structured prompts:

[主体] + [场景 / 环境] + [风格] + [光照] + [构图] + [质量要求]

Good example for text-to-image:

A futuristic city marketplace filled with flying vehicles, holographic signs, dense crowds, neon lighting, cinematic realism, ultra-detailed, high-information-density composition

Good example for image-to-image(also specify modification requirements and preservation requirements):

Convert the image into a fantasy winter landscape, add snow, warm window lights, and a magical atmosphere, while preserving the original building structure and camera angle.

Recommended structure:

[修改要求] + [新风格 / 新场景] + [需要添加或移除的元素] + [需要保留的元素]

Base64 transmission instructions

This skill uniformly uses Base64 to transmit images:

Text-to-image output: specified via extra_body.response_format: "b64_json" specified, in the response data[0].b64_json is the image Base64 data (pure base64, no prefix).
Image-to-image input: local images are automatically converted to Data URI format data:image/png;base64,XXX, placed into the extra_body.image array.
Image-to-image output: specified via extra_body.response_format: "b64_json" specified, in the response data[0].b64_json is the image Base64 data.

Client writes to file:Buffer.from(b64_str, 'base64') → write to disk

Note: the text-to-image Base64 output example in the official documentation uses the top-level "return_base64": true, but testing shows this parameter is ignored by the API (it still returns a URL). This skill uniformly uses extra_body.response_format: "b64_json", which is effective for both text-to-image and image-to-image.

Notes

The API key must be set, and can be provided via the environment variable AGNES_API_KEY or the command-line parameter -k provided
Image generation time: about 60-360 seconds; complex high-density scenarios may take longer
Text-to-image and image-to-image use the same endpoint /v1/images/generations, both via JSON requests
Output images are uniformly in PNG format (no quality, output_format, or other parameters)
When editing images, up to 5 input images are allowed; each image is automatically base64-encoded before upload
Ensure the output directory has write permission

API Key setup and acquisition

How to obtain an API Key

If you do not yet have an API key, please go to https://www.agnes-ai.com to register an account and apply for an API Key.

Acquisition steps:

Visit https://www.agnes-ai.com
Register/log in to your account
Create an API key in the console
Copy the key and set an environment variable or use it on the command line

Set the API Key

The script looks up the API key in the following order:

--api-key / -k Command-line parameter (temporary use)
AGNES_API_KEY Environment variable (recommended)

Set the environment variable:

# Linux/Mac
export AGNES_API_KEY="your-api-key-here"

# Windows CMD
set AGNES_API_KEY=your-api-key-here

# Windows PowerShell
$env:AGNES_API_KEY="your-api-key-here"

API endpoint instructions

Endpoint: POST https://apihub.agnes-ai.com/v1/images/generations

Text-to-image and image-to-image share the same endpoint and use JSON-format requests.

Authentication Header：Authorization: Bearer YOUR_API_KEY
Content-Type：application/json

Text-to-image (Base64 output)

{
  "model": "agnes-image-2.1-flash",
  "prompt": "...",
  "size": "1024x768",
  "extra_body": {
    "response_format": "b64_json"
  }
}

Image-to-image (Data URI Base64 input + Base64 output)

{
  "model": "agnes-image-2.1-flash",
  "prompt": "...",
  "size": "1024x768",
  "extra_body": {
    "image": [
      "data:image/png;base64,XXXXX"
    ],
    "response_format": "b64_json"
  }
}

Response format (Base64 output)

{
  "created": 1780000000,
  "data": [
    {
      "url": null,
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": null
    }
  ]
}

Model information

Model name:agnes-image-2.1-flash
Generation speed: about 60-360 seconds
Output resolution: custom size, for example 1024x768、1536x1024、2048x2048
Output format: PNG (fixed)
Supported capabilities: text-to-image, single-image editing, multi-image fusion, high-information-density image optimization
Price: $0.003/image
Input method: Data URI Base64 (image-to-image)

Common errors and troubleshooting

1. `response_format` placed at the top level causes an error

Do not place response_format at the top level of the request body; it must be placed in extra_body .

Incorrect example:

{
  "model": "agnes-image-2.1-flash",
  "prompt": "...",
  "size": "1024x768",
  "response_format": "b64_json"
}

Correct example: see "API Endpoint Description" above.

2. Text-to-image returns a URL by default instead of Base64

The official documentation's text-to-image Base64 output example uses the top-level "return_base64": true, but in practice this parameter is ignored by the API, and it still returns url。

✅ Recommended practice: use consistently with image-to-image extra_body.response_format: "b64_json", which is effective for both text-to-image and image-to-image (this skill has adopted this approach).

3. Image-to-image request is missing `image`

In an image-to-image request,image array is required.

4. Input image URL is inaccessible

This skill has uniformly adopted Data URI Base64 for input images, avoiding public URL accessibility issues.

5. Request timeout

Image generation may take 60-360 seconds, depending on prompt complexity, image size, and service load. The script timeout has been set to 360 seconds.

Author Introduction

Omnipresent Loves Pirates
My WeChat official account: Omnipresent Technology