Image Generation and Editing (Official Formal Version of GPT Image 2)

Usage Guide

Step 1: Analyze Requirements and Extract Parameters

1. Clarify Intent: Distinguish whether the user needs [Text-to-Image] (generate new images), [Image-to-Image] (edit/modify existing images), or [Multi-Image Fusion].
2. Prompt Analysis:
   • Use the user's original complete input: Directly use the user's original full question and requirement description as the main body of the

     -p

     prompt. Avoid rewriting, summarizing or secondary creation on your own to prevent loss of details.
   • Confirm first when supplementation is needed: If information is insufficient (e.g., missing style, number of subjects, shot language, scene details, text content, prohibited elements, etc.), ask the user for confirmation first; after the user confirms, append the supplementary content to the original prompt in an "appending" manner.
   • Examples:
     • User input: "Help me generate a picture of a cat, in a cute style."
     • Correct example: Use the user's input directly as the prompt:

       -p "Help me generate a picture of a cat, in a cute style."

     • Incorrect example: Unauthorized rewriting to "Generate a picture of a cat in cute style" will lose the details and tone of the user's original input.
     • If additional details are needed (e.g., color, background, etc.), ask for confirmation first: "What color do you want the cat to be? Any requirements for the background?" After the user replies, append it to the prompt:

       -p "Help me generate a picture of a cat, in a cute style. The cat is orange, and the background is grass."

3. Key Parameter Organization:
   • Prompt (Required): The final prompt after analysis (default = the user's original complete and consistent input; only append supplementary information after user confirmation).
   • Filename (Optional): Output image filename/path (must include a random 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 content (e.g.,

     cat_in_garden.png

     ) instead of using generic names.
   • Size (Optional): Output size.
     • Preset values:

       1024x1024

       ,

       1536x1024

       ,

       1024x1536

       ,

       2048x2048

       ,

       2048x1152

       ,

       3840x2160

       ,

       2160x3840

     • Custom sizes are also allowed (requirements: maximum side ≤3840, both sides are multiples of 16, aspect ratio ≤3:1, total pixels 0.65–8.3MP)
     • Default is model-adaptive (auto)
   • Quality (Optional): Quality level.

     low

     (sketch/batch),

     medium

     (daily use),

     high

     (final draft/fine text),

     auto

     (default)
   • Output Format (Optional):

     png

     (default),

     jpeg

     ,

     webp

   • Output Compression (Optional): Output compression rate (0-100), only valid for jpeg/webp
   • Note: This model uses official formal endpoints, which are different from the reverse version gpt-image-2-all.

Step 2: Environment Check and Command Execution

1. Check Environment: Confirm whether the

   APIYI_API_KEY

   environment variable is set (usually assumed to be set; prompt the user if execution fails).
2. Build and Run Commands:
   • Priority Node.js Version: If Node is available in the environment (the

     node

     command works), prefer using

     scripts/generate_image.js

     (zero dependencies, parameters are consistent with Python).
   • Use Python Version if Node is Unavailable: Use

     scripts/generate_image.py

     .
   Text-to-Image Command Template (Priority Node.js):
   bash

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

   Image-to-Image Command Template (Priority Node.js):
   bash

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

   Multi-Image Fusion Command Template (Priority Node.js):
   bash

   node scripts/generate_image.js -p "Merge the styles of Image 1 and Image 2" -i ref1.png ref2.png -f "merged.png" [-s {size}] [-q {quality}]

   (Optional) Python Version Command Template (When Node is Unavailable):
   bash

   python scripts/generate_image.py -p "{prompt}" -f "{filename}" [-s {size}] [-q {quality}] [-o {output_format}]
   python scripts/generate_image.py -p "{edit_instruction}" -i "{input_path}" -f "{output_filename}" [-s {size}] [-q {quality}]

⏱️ Long-running Task Processing Strategy

1. Pre-task Prompt

• "Image generation has started, it is expected to take 120-150 seconds, please wait patiently"

2. 🎨 Best Practice Example

"Image generation in progress, expected to complete in 120-150 seconds...\n⏳ Generating...\n(Complex scenes with high quality + 2K/4K may take longer, please wait patiently)"

Step 3: Result Feedback

1. Execution Feedback: Wait for the terminal command to complete execution.
2. Success: Inform the user that the image has been generated and indicate the save path.
3. Failure:
   • If prompted for missing API Key, guide the user to set the environment variable.
   • If prompted for network error, suggest the user check the network or try again later.

Command Line Usage Examples

Generate New Images

python scripts/generate_image.py -p "Image description text" -f "output.png" [-s {size}] [-q {quality}] [-o {output_format}]

# Basic generation
python scripts/generate_image.py -p "A cute orange cat playing on the grass" -f "cat.png"

# Specify size and quality
python scripts/generate_image.py -p "Sunset mountain landscape" -f "sunset.png" -s "2048x1152" -q "high"

# Vertical HD image (suitable for mobile wallpaper)
python scripts/generate_image.py -p "City night view" -f "city.png" -s "2160x3840" -q "high"

# Output as JPEG
python scripts/generate_image.py -p "Landscape photo" -f "landscape.jpg" -s "3840x2160" -q "high" -o "jpeg"

# Basic generation
node scripts/generate_image.js -p "A cute orange cat playing on the grass" -f "cat.png"

# Specify size and quality
node scripts/generate_image.js -p "Sunset mountain landscape" -f "sunset.png" -s "2048x1152" -q "high"

Edit Existing Images

python scripts/generate_image.py -p "Editing instruction" -f "output.png" -i "path/to/input.png" [-s {size}] [-q {quality}]

# Modify style
python scripts/generate_image.py -p "Convert the image to watercolor style" -f "watercolor.png" -i "original.png"

# Add elements
python scripts/generate_image.py -p "Add a rainbow to the sky" -f "rainbow.png" -i "landscape.png" -q "high"

# Replace background
python scripts/generate_image.py -p "Change the background to a beach" -f "beach-bg.png" -i "portrait.png" -s "2048x2048"

# Modify style
node scripts/generate_image.js -p "Convert the image to watercolor style" -f "watercolor.png" -i "original.png"

# Multi-reference image fusion (up to 5 images)
node scripts/generate_image.js -p "Put the character from Image 1 into the scene of Image 2" -i ref1.png ref2.png -f "merged.png"

Command Line Parameter Description

Parameters are consistent between Python and Node.js versions (short parameters are equivalent to long parameters).

-p

--prompt

-f

--filename

-s

--size

-q

--quality

-o

--output-format

-c

--output-compression

-i

--input-image

File Resource Description

scripts/generate_image.js

scripts/generate_image.py

references/size-guide.md

references/batch-template.md

Batch Generation

1. Load Configuration Template: references/batch-template.md — includes JSON configuration format description and usage examples
2. Obtain/Generate JSON File: Users can provide their own JSON file, or describe requirements and let AI generate it based on the requirements
3. Execute One by One: Read the prompts array, execute the generation command one by one, and feedback the result after each image is completed
4. Summary Feedback: After completion, inform the user of the number of successful images and the list of image paths

Note: Total time for batch tasks = single image time (120-150 seconds) × number of images, please inform the user of the estimated duration in advance.

Quality Description

Output Format Description

data:image/...;base64,

• Write to file:

  base64.b64decode(b64_str)

  → write to disk
• Render in browser: Append the prefix

  data:image/png;base64,

  + b64 on your own

Notes

• API Key must be set, can be provided via environment variable or command line parameter
• Image generation time: Approximately 120-150 seconds, complex scenes with high quality + 2K/4K may take longer
• When editing images, use multipart/form-data to upload reference images
• Ensure the output directory has write permission
• Billed by token (not per image)

API Key Setup and Acquisition

How to Obtain API Key

1. Visit https://api.apiyi.com
2. Register/login your account
3. Create an API Key in the console
4. Copy the key and set the environment variable or use it in the command line

Set API Key

APIYI_API_KEY

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

Set environment variable in advanced settings of your computer or execute the set command:
# Windows CMD
set APIYI_API_KEY=your-api-key-here

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

API Endpoint Description

Text-to-Image Endpoint: POST /v1/images/generations

Image-to-Image Endpoint: POST /v1/images/edits

Model Information

• Model Name: gpt-image-2
• Image Generation Speed: Approximately 120-150 seconds (4K complex scenes may take longer)
• Output Resolution: 1024x1024 / 1536x1024 / 1024x1536 / 2048x2048 / 2048x1152 / 3840x2160 / 2160x3840 or custom
• Default Response Format: b64_json (pure base64, no prefix)
• Quality Levels: low / medium / high / auto
• Output Formats: png / jpeg / webp
• Supported Capabilities: Text-to-image, single image editing, multi-image fusion
• Billing Method: Billed by token

Comparison between gpt-image-2 (Official Formal Version) vs gpt-image-2-all (Official Reverse Version)

Author Introduction

• LoveOnePiece_Ubiquitous
• My WeChat Official Account: Ubiquitous Technology