README.md

---
title: Outpaint
emoji: 🐢
colorFrom: yellow
colorTo: red
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
---

> **Note:** This README was generated with assistance from GPT and should be verified against the current implementation.

# Outpaint

Outpaint is a small Gradio application that extends an image in one direction with Google's Gemini image-generation model (`gemini-2.5-flash-image`, nicknamed Nano Banana in the UI).

The app pads the selected edge with chroma-key green, generates an editable instruction describing which region to fill, sends the padded image and prompt to Gemini, and displays the returned image. A generated result can be reused as the next input for iterative expansion.

## Workflow

1. Upload an image.
2. Choose top, bottom, left, or right and select 50–500 pixels of padding.
3. Inspect the green padded preview and optionally edit the generated prompt.
4. Click **Outpaint with Nano Banana**.
5. Optionally click **Reuse Outpainted Image** and repeat in another direction.

All image state lives in the Gradio session. The application does not implement persistent storage or a separate HTTP API route.

## Project layout

| Path | Purpose |
| --- | --- |
| `app.py` | Image padding, Gemini request handling, Gradio UI, and event wiring |
| `requirements.txt` | Pillow and Google Gen AI SDK dependencies |
| `README.md` | Hugging Face Space metadata and project documentation |

## Prerequisites

- Python 3.10 or newer
- A Google Gemini API key with access to `gemini-2.5-flash-image`
- Network access to Google's Generative AI API

The hosted Space provides Gradio 5.49.1. Install it explicitly for local development because `requirements.txt` does not list Gradio.

## Configuration

| Variable | Required | Purpose |
| --- | --- | --- |
| `GEMINI_API_KEY` | Yes | Authenticates `google-genai` requests |

The Gemini client is created when `app.py` is imported, so set the variable before starting Python. Never commit API keys.

## Run locally

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install "gradio==5.49.1"

export GEMINI_API_KEY="..."
python app.py
```

Open `http://127.0.0.1:7860` and follow the workflow above. The app starts Gradio with debug logging enabled.

## Hugging Face Space notes

- Repository: `GFHLabs/Outpaint`
- SDK: Gradio 5.49.1
- Entry point: `app.py`
- Add `GEMINI_API_KEY` under **Settings → Variables and secrets** as a secret.
- Pushing changes to the Space repository triggers a rebuild/restart.
- The generated image is returned by the model; the code does not preserve source or output files outside Gradio's temporary handling.

## Troubleshooting

- **Authentication or permission error:** confirm `GEMINI_API_KEY` is set before startup and that the key can use `gemini-2.5-flash-image` in the current account/region.
- **No image is returned:** inspect the runtime logs. When the response contains no inline image data, the app intentionally returns the padded input and labels it as “no result from API.”
- **Green remains in the result:** make the custom prompt explicitly require the entire green region to be replaced, or reduce the padding and retry.
- **The extension looks inconsistent:** use a smaller padding amount and describe the expected scene continuation, lighting, perspective, and objects in the custom prompt.
- **An edit appears to use stale state:** click a direction after uploading or reusing an image; that action refreshes the padded image and direction state.
- **Local import error for Gradio:** install the metadata-pinned version shown above; it is supplied by Hugging Face but omitted from `requirements.txt`.