Partial Image

中文

Coded with GPT-5.5 for the GPT-image-2 partial image API demo and testing.

A local web tool for debugging and demonstrating streamed intermediate images from the OpenAI image generation API. The project supports text-to-image generation, image editing with reference images, real-time partial image previews, prompt optimization, and local saving of output images and run metadata.

Standard UI	Crayon Style

Features

• Preview partial images in real time during image generation
• Generate images from text prompts
• Edit images with uploaded reference images
• Export PNG, JPEG, or WebP images
• Configure size, quality, compression, background, and moderation options
• Optimize image generation prompts with one click
• Save generated images, uploaded inputs, and metadata.json for each run
• Replay the bundled river*.png sample images without calling the API

Project Structure

partial_image/
├── index.html          # Frontend page
├── web_app.py          # FastAPI backend service
├── partial_image.py    # Minimal partial image API example script
├── river0.png          # Sample partial image
├── river1.png          # Sample partial image
├── river2.png          # Sample final image
├── runs/               # Local output directory, do not commit to GitHub
└── .env                # Local environment variables, do not commit to GitHub

Requirements

• Python 3.10 or later
• API key(s) for the features you use

Install dependencies:

pip install -r requirements.txt

Or install them manually:

pip install openai python-dotenv fastapi uvicorn python-multipart

Environment Variables

Configure API credentials in partial_image/.env:

use the partial_image/.env_sample file as a template.

OPENAI_BASE_URL= https://openai.com/v1
OPENAI_API_KEY= YOUR_IMAGE_API_KEY
IMAGE_MODEL=gpt-image-2

# Optional prompt optimization overrides.
OPTIMIZE_BASE_URL= your_optimize_api_base_url
OPTIMIZE_API_KEY= YOUR_OPTIMIZE_API_KEY
OPTIMIZE_TEXT_MODEL=gpt-5.5

# Optional Responses API generation overrides.
RESPONSE_BASE_URL= your_responses_api_base_url
RESPONSE_API_KEY= YOUR_RESPONSE_API_KEY
RESPONSE_MODEL=gpt-5.5
RESPONSE_IMAGE_MODEL=gpt-image-2

Run The Web App

Run this from the project root:

cd partial_image
uvicorn web_app:app --reload --host 127.0.0.1 --port 8000

Then open:

http://127.0.0.1:8000

Usage

Generate Images

1. Enter an image prompt in the web page.
2. Choose Images API or Responses API for text-to-image generation.
3. Choose size, quality, output format, and other parameters.
4. Set partial_images to 1, 2, or 3 to preview intermediate images while generation is running.
5. Start generation. The page will show partial images first, then the final image.

Responses API mode only applies when no reference images are uploaded. Reference-image edit mode always uses the Images API.

Generated results are saved to:

partial_image/runs/<timestamp>/

Each run directory usually contains:

• partial_*.png: intermediate images
• final_*.png: final images
• metadata.json: prompt, parameters, and input image metadata
• inputs/: uploaded reference images

Edit With Reference Images

Upload PNG, JPEG, or WebP images in the page before generating. The backend will call the image editing API instead of plain text-to-image generation.

Limits:

• Up to 16 reference images
• Maximum 50 MB per image
• PNG, JPEG, and WebP are supported

Replay Sample Images

The project includes river0.png, river1.png, and river2.png. You can use the replay feature in the web page to preview the partial image display flow without making an API request.

Minimal Script Example

You can also run partial_image.py directly:

cd partial_image
python partial_image.py

The script requests one image generation and saves streamed partial images as river0.png, river1.png, and river2.png.

API Endpoints

POST /api/generate

Generate or edit images. The response is an NDJSON stream.

Example JSON request:

{
  "prompt": "A river made of white owl feathers winding through a quiet winter forest",
  "api_mode": "images",
  "size": "1024x1024",
  "quality": "auto",
  "partial_images": 2,
  "image_count": 1,
  "output_format": "png",
  "background": "auto",
  "moderation": "auto"
}

POST /api/optimize-prompt

Optimize an image generation prompt.

{
  "prompt": "A feather river in the snow"
}

POST /api/replay

Replay the bundled river*.png sample images from the project directory.