GPT Image 2 (gpt-image-2) — Python & Node.js API Examples

Drop-in Python (fal-client) and Node.js (@fal-ai/client) examples for OpenAI's GPT Image 2.0 model — the image generation model behind ChatGPT's image features — powered by fal.ai. Text-to-image and image editing, plus an optional gpt-image-2 Python wrapper and CLI.

_{Also known as: ChatGPT Image 2, ChatGPT Images 2.0, GPT Image 2.0 API, OpenAI gpt-image-2 API, ChatGPT image generator API.}

What is this repo? Copy-paste-ready Python and Node.js examples for calling GPT Image 2 (gpt-image-2) — OpenAI's GPT Image 2.0 image model, the same model that powers ChatGPT's image generation — through fal.ai's hosted API. It covers both endpoints: text-to-image (openai/gpt-image-2) and image editing (openai/gpt-image-2/edit). Every Python snippet below uses the official fal-client SDK directly, with zero extra abstractions — the kind of code you'd actually paste into your own project. This repo also ships an optional tiny wrapper (pip install gpt-image-2) and a gpt-image-2 CLI for ergonomics.

Searching for "ChatGPT Image 2 API" or "ChatGPT Images 2.0"? You're in the right place. ChatGPT's in-product image generator is powered by OpenAI's gpt-image-2 model — the same model this repo calls through fal.ai. See the ChatGPT vs gpt-image-2 FAQ for the full clarification.

▶ Try GPT Image 2 on the fal.ai playground: Text-to-image · Edit / image-to-image · API docs · Prompt examples

Features

Drop-in Python examples using fal-client directly — paste straight into your project.
Matching Node.js examples using @fal-ai/client.
Covers text-to-image and image editing (with optional mask).
Streaming (stream), queue (submit / status / result), and webhook support.
Resolutions up to 3840 px edge (~4K), strong typography, commercial-use friendly.
Optional tiny wrapper: pip install gpt-image-2 for a one-liner API and a gpt-image-2 CLI.
MIT licensed.

Why gpt-image-2 (via fal.ai)?

Best-in-class typography. gpt-image-2 renders clean on-image text reliably — great for infographics, posters, and album art.
Fine-grained edits. The /edit endpoint accepts one or more reference images plus an optional mask.
Up to 3840 px edge with flexible aspect ratios up to 3:1.
Fal.ai hosting gives you commercial licensing, streaming, and a queue + webhook flow out of the box.

Python quickstart

1. Install

pip install fal-client

2. Set your fal.ai API key

export FAL_KEY="your-fal-api-key"    # get one at https://fal.ai/dashboard/keys

3. Generate an image

import fal_client

def on_queue_update(update):
    if update.status == "IN_PROGRESS":
        for log in update.logs or []:
            print(log["message"])

result = fal_client.subscribe(
    "openai/gpt-image-2",
    arguments={
        "prompt": "a cinematic product shot of a red sneaker on wet asphalt, 4k",
        "image_size": "landscape_16_9",
        "quality": "high",
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result["images"][0]["url"])

4. Edit an image

import fal_client

result = fal_client.subscribe(
    "openai/gpt-image-2/edit",
    arguments={
        "prompt": "Wrap the bus with this branding as a full livery. Keep everything else unchanged.",
        "image_urls": [
            "https://example.com/bus.png",
            "https://example.com/livery.png",
        ],
        "image_size": "auto",
        "quality": "high",
    },
    with_logs=True,
)
print(result["images"][0]["url"])

Also see the ready-to-run scripts in python/:

python/text_to_image.py
python/edit_image.py
python/text_to_image_stream.py
python/queue_submit.py
python/examples/ — runnable versions of every prompt in the prompts gallery.

Optional: `gpt-image-2` wrapper + CLI

For one-liners and a CLI, install the thin wrapper shipped in this repo:

pip install gpt-image-2                 # or:  pip install -e .  (from this repo)

import gpt_image_2
print(gpt_image_2.generate("a cute corgi astronaut, 4k").first_url)

gpt-image-2 generate "a cute corgi astronaut" --size landscape_16_9 --quality high
gpt-image-2 edit "make it night-time" --image https://example.com/scene.png

Node.js quickstart

1. Install

cd node
npm install

2. Set your fal.ai API key

export FAL_KEY="your-fal-api-key"

3. Generate an image

node text-to-image.js "a cinematic product shot of a red sneaker on wet asphalt, 4k"

Or in code:

import { fal } from "@fal-ai/client";

const result = await fal.subscribe("openai/gpt-image-2", {
  input: {
    prompt: "a cinematic product shot of a red sneaker on wet asphalt, 4k",
    image_size: "landscape_16_9",
    quality: "high",
  },
  logs: true,
});
console.log(result.data.images[0].url);

Full Node.js examples: node/.

Text-to-image API

Endpoint: openai/gpt-image-2

Field	Type	Default	Notes
`prompt`	string (required)	—	The prompt. Use quotes for any exact on-image text.
`image_size`	preset or `{width, height}`	`landscape_4_3`	Both dims multiples of 16, max edge 3840 px, aspect ≤ 3:1.
`quality`	`low` \| `medium` \| `high`	`high`
`num_images`	integer	`1`
`output_format`	`jpeg` \| `png` \| `webp`	`png`
`sync_mode`	boolean	`false`	If `true`, returns a data URI.

Presets: square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9.

Full docs: docs/text-to-image.md.

Image edit API

Endpoint: openai/gpt-image-2/edit

Field	Type	Default	Notes
`prompt`	string (required)	—	Edit instruction.
`image_urls`	list (required)	—	One or more reference images. URL or `data:` URI.
`mask_url`	string	none	Optional mask for region-specific edits.
`image_size`	preset, `auto`, or `{width, height}`	`auto`	`auto` inherits input dims.
`quality`	`low` \| `medium` \| `high`	`high`
`num_images`	integer	`1`
`output_format`	`jpeg` \| `png` \| `webp`	`png`

Full docs: docs/edit-image.md.

Streaming and queue

# Python streaming with fal-client
import fal_client
for event in fal_client.stream(
    "openai/gpt-image-2",
    arguments={"prompt": "a surreal oil painting of Mars at sunrise"},
):
    print(event)

# Python queue + webhook with fal-client
import fal_client

handle = fal_client.submit(
    "openai/gpt-image-2",
    arguments={"prompt": "a cinematic sunset over the Himalayas, 4k"},
    webhook_url="https://your.app/api/fal/webhook",
)
result = fal_client.result("openai/gpt-image-2", request_id=handle.request_id)

// Node.js streaming
import { fal } from "@fal-ai/client";
const stream = await fal.stream("openai/gpt-image-2", { input: { prompt: "…" } });
for await (const event of stream) console.log(event);

Full guide: docs/streaming.md.

Image sizes & quality

Preset	Typical dims
`square_hd`	1024 x 1024
`square`	512 x 512
`portrait_4_3`	~ 768 x 1024
`portrait_16_9`	~ 720 x 1280
`landscape_4_3`	~ 1024 x 768
`landscape_16_9`	~ 1280 x 720
`auto` (edit only)	inferred from input

Constraints: multiples of 16; max edge 3840 px; aspect ≤ 3:1; total pixels 655,360–8,294,400. Full cheatsheet: docs/image-sizes.md.

Prompts gallery

Runnable, copy-paste prompts lifted from fal.ai's text-to-image and edit example galleries:

Recursive hero infographic — python · node
Photorealistic corporate boardroom — python · node
Broadcast news anchor ("BREAKING: GPT-IMAGE-2 NOW LIVE ON fal") — python · node
Creative studio review wall — python · node
Vinyl album cover edit — python · node
Bus livery multi-image edit — python · node

More: docs/prompts-gallery.md.

CLI (optional wrapper)

The optional gpt-image-2 wrapper ships a CLI:

pip install gpt-image-2
gpt-image-2 generate "a cinematic product shot of a red sneaker" --size landscape_16_9 --quality high
gpt-image-2 generate "poster art" --size 1280x720 -n 2 --format webp
gpt-image-2 edit "make it night-time, neon reflections" --image https://example.com/in.png

Run gpt-image-2 --help for full flags. Prefer raw fal-client? Every example in this repo's python/ folder is written that way.

FAQ

See docs/faq.md. A few highlights:

What is gpt-image-2? OpenAI's next-gen image model, focused on high-res output, strong typography, and fine-grained editing. Hosted on fal.ai as openai/gpt-image-2 and openai/gpt-image-2/edit.
Is gpt-image-2 the same as the ChatGPT image generator? ChatGPT's in-product image generation is powered by gpt-image-2 — the model this repo calls directly. So "ChatGPT Image 2 API", "ChatGPT Images 2.0 API", and "gpt-image-2 API" are all the same underlying model. ChatGPT is the product; gpt-image-2 is the model id.
Do I need the wrapper? No. Every example in this repo uses fal-client directly. The gpt-image-2 pip package is just optional sugar + a CLI.
Max resolution? 3840 px max edge, up to ~8.3 MP total, aspect ≤ 3:1.
Does it support editing? Yes — the /edit endpoint accepts one or more reference images and an optional mask.
Is there streaming? Yes — both endpoints support streaming and a queue/webhook flow.
Can I use it commercially? Yes, fal.ai's model page marks it as commercial-use-friendly. This wrapper is MIT licensed.

Resources

fal.ai playground (text-to-image): https://fal.ai/models/openai/gpt-image-2
fal.ai playground (edit): https://fal.ai/models/openai/gpt-image-2/edit
API reference (text-to-image): https://fal.ai/models/openai/gpt-image-2/api
API reference (edit): https://fal.ai/models/openai/gpt-image-2/edit/api
Prompt examples (text-to-image): https://fal.ai/models/openai/gpt-image-2/examples
Prompt examples (edit): https://fal.ai/models/openai/gpt-image-2/edit/examples

Repository topics

This repo uses the following GitHub topics so GitHub search and Google can find it. The full list lives in .github/topics.txt; apply them after pushing to GitHub with:

bash scripts/apply-github-topics.sh                # uses current `origin`
# or explicitly:
bash scripts/apply-github-topics.sh amrrs/chatgpt-images-2-api

_{gpt-image-2 · gpt-image-2-api · chatgpt-image-2 · chatgpt-images-2 · chatgpt-image-generator · openai · openai-api · fal-ai · image-generation · image-generation-api · text-to-image · image-editing · image-to-image · ai-image-generation · generative-ai · api-wrapper · python · nodejs · sdk · image-api}

Contributing

PRs are welcome — especially new prompt examples. Add a script under python/examples/ and node/examples/, then extend docs/prompts-gallery.md.

License

MIT. "GPT Image 2", "gpt-image-2", and "OpenAI" are trademarks of their respective owners — this project is an independent, unofficial wrapper.

Powered by fal.ai. If you build something cool with GPT Image 2, tag fal on X — they feature community work.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github		.github
docs		docs
gpt_image_2		gpt_image_2
node		node
python		python
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

GPT Image 2 (gpt-image-2) — Python & Node.js API Examples

Table of contents

Features

Why gpt-image-2 (via fal.ai)?

Python quickstart

1. Install

2. Set your fal.ai API key

3. Generate an image

4. Edit an image

Optional: `gpt-image-2` wrapper + CLI

Node.js quickstart

1. Install

2. Set your fal.ai API key

3. Generate an image

Text-to-image API

Image edit API

Streaming and queue

Image sizes & quality

Prompts gallery

CLI (optional wrapper)

FAQ

Resources

Repository topics

Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

GPT Image 2 (gpt-image-2) — Python & Node.js API Examples

Table of contents

Features

Why gpt-image-2 (via fal.ai)?

Python quickstart

1. Install

2. Set your fal.ai API key

3. Generate an image

4. Edit an image

Optional: gpt-image-2 wrapper + CLI

Node.js quickstart

1. Install

2. Set your fal.ai API key

3. Generate an image

Text-to-image API

Image edit API

Streaming and queue

Image sizes & quality

Prompts gallery

CLI (optional wrapper)

FAQ

Resources

Repository topics

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Optional: `gpt-image-2` wrapper + CLI

Packages