Gpt Image 2

interface:
  display_name: "GPT Image 2"
  short_description: "Complete GPT Image 2 skill for generations, edits, and responses."
  default_prompt: "Use $gpt-image-2 to generate, edit, or stream GPT Image 2 outputs through an OpenAI-compatible API."


# gpt-image-2

An agent skill for the full **GPT Image 2** surface on any OpenAI-compatible gateway. One Python entrypoint covers `images/generations`, `images/edits`, and `responses` (with the `image_generation` tool), including streaming and partial-image previews.

Built for Codex, Claude, and other skill-aware agents, but the script also runs fine by hand.

## Features

- Three subcommands in one CLI: `generations`, `edits`, `responses`.
- Text-to-image, multi-image batches, mask edits, multi-reference edits, mixed text + image input.
- Streaming (SSE) with optional `partial_images` progressive previews.
- Strict pre-flight validation of GPT Image 2 constraints (size, aspect, pixel count, transparent background, `output_compression`, `stream` + `n`, and unsupported `response_format` usage on OpenAI GPT image models).
- Automatic base64 de-duplication and multi-image filename templating (`out-{index}.png`).
- Config via CLI flags, process environment, or `.env` — with a predictable override order.
- Zero third-party dependencies (standard library only).

## Requirements

- Python 3.10+
- An OpenAI-compatible endpoint that serves `gpt-image-2` (default: `https://api.openai.com/v1`).
- For `responses`, a text-capable Responses model such as `gpt-5.4` when using the hosted `image_generation` tool.
- `OPENAI_API_KEY`.

## Install

After publishing the repository, the recommended install path is through [Skills](https://skills.sh/):

```powershell
pnpm dlx skills add https://github.com/GargantuaX/openskills --skill gpt-image-2
```

Equivalent shorthand:

```powershell
pnpm dlx skills add GargantuaX/openskills@gpt-image-2
```

If you want the whole collection instead, install:

```powershell
pnpm dlx skills add GargantuaX/openskills
```

You can also drop the folder into your agent's skill directory, or clone/copy it anywhere and invoke the script directly.

Register with Codex by pointing at [agents/openai.yaml](./agents/openai.yaml). Claude-style agents can consume [SKILL.md](./SKILL.md) directly.

## Setup After skills.sh Install

1. Set credentials with environment variables, or create a `.env` in the working directory where you will run the script.
2. Start from the repository example [`.env.example`](../../.env.example), then adjust values for your endpoint and model defaults.
3. Run a `--dry-run` command first to confirm the final request shape before making live requests.

Minimal `.env`:

```dotenv
OPENAI_API_KEY=your-openai-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_IMAGE_MODEL=gpt-image-2
OPENAI_RESPONSES_MODEL=gpt-5.4
OPENAI_IMAGE_SIZE=auto
OPENAI_IMAGE_QUALITY=high
OPENAI_IMAGE_FORMAT=webp
OPENAI_IMAGE_TIMEOUT=300
```

Dry-run check:

```powershell
python .\scripts\gpt_image.py responses `
  --input-text "Generate a poster for an AI tool launch" `
  --output .\out\poster.webp `
  --dry-run
```

## Quick start

```powershell
# 1. Configure credentials (either export or put in .env next to the script)
$env:OPENAI_API_KEY = "sk-..."
$env:OPENAI_BASE_URL = "https://api.openai.com/v1"

# 2. Generate
python .\scripts\gpt_image.py generations `
  --prompt "A bold product hero image" `
  --output .\out\hero.webp
```

Built-in defaults now match the example `.env`: `size=auto`, `quality=high`, `format=webp`, `timeout=300`. For `responses`, the default top-level model is `gpt-5.4`; `OPENAI_IMAGE_MODEL` only applies to `generations` and `edits`.

See [SKILL.md](./SKILL.md) for the full command catalog, including multi-image batches, masked edits, and streaming Responses.

## Project layout

```
gpt-image-2/
├─ SKILL.md                  # Agent-facing entry point (workflow + examples + rules)
├─ README.md                 # You are here
├─ agents/
│  └─ openai.yaml