openai/gpt-image-2/edit

Run GPT Image 2.0 AI Image Editor API on fal

OpenAI's next-generation image model, now available as an image editing API via fal. Make fine-grained, detailed edits to existing images using natural language prompts and optional mask control.

Overview

`openai/gpt-image-2/edit` exposes GPT Image 2 as an image-to-image editing endpoint. Provide one or more reference images alongside a text prompt and the model will apply targeted edits while preserving the parts of the image you did not ask to change. For precise control over which region gets edited, pass an optional mask image to constrain the generation area.

This is the same underlying model as `fal-ai/gpt-image-2/`, optimized specifically for editing workflows rather than generation from scratch.

Streaming supported. This endpoint supports real-time streaming, so you can display partial results as they arrive rather than waiting for the full generation to complete.

Pricing

The following table shows the pricing of GPT-Image-2 from a technical standpoint.

This implies the following: Longer prompts increase the cost, more complex requests (involving use of world knowledge, etc.) cost more, and larger images cost more.

What it can do

Fine-Grained Edits from Natural Language

Describe the change you want in plain text and the model applies it with precision. Style, lighting, objects, clothing, text overlays, and scene details can all be targeted through the prompt alone, without any masking required.

Mask-Based Inpainting

For surgical edits, pass a `mask_image_url` alongside your reference image. The white regions of the mask indicate the areas to edit; everything outside remains pixel-perfect. This is ideal for product photography touch-ups, background replacements, and UI asset updates.

Multi-Image Reference

The `image_urls` field accepts a list of images. This allows the model to draw context from multiple sources, useful for style transfer, composition blending, or editing images that require cross-reference context.

Auto Size Inference

When `image_size` is set to `auto` (the default for this endpoint), the model infers the output dimensions from the input image. This avoids accidental cropping or rescaling when editing existing assets.

Real-Time Streaming

Stream the result token by token as it is generated. Useful for interactive editing tools where responsiveness matters more than waiting for a polished final output.

Quick Start

Install the client

bash
npm install --save @fal-ai/client

Set your API key

bash
export FAL_KEY="YOUR_API_KEY"

Basic image edit

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

const result = await fal.subscribe("openai/gpt-image-2/edit", {
  input: {
    prompt: "Change the background to a rainy Tokyo street at night",
    image_urls: ["https://your-image-url.com/photo.png"],
  },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});

console.log(result.data.images[0].url);

Edit with a mask

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

const result = await fal.subscribe("openai/gpt-image-2/edit", {
  input: {
    prompt: "Replace the sky with a dramatic sunset",
    image_urls: ["https://your-image-url.com/photo.png"],
    mask_image_url: "https://your-image-url.com/sky-mask.png",
    quality: "high",
    output_format: "png",
  },
});

console.log(result.data.images[0].url);

Streaming

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

const stream = await fal.stream("openai/gpt-image-2/edit", {
  input: {
    prompt: "Change the lighting to golden hour",
    image_urls: ["https://your-image-url.com/photo.png"],
  },
});

for await (const event of stream) {
  console.log(event);
}

const result = await stream.done();

API Reference

Input

Image size presets

Custom dimensions are also supported. Both edges must be multiples of 16:

json
"image_size": {
  "width": 1920,
  "height": 1080
}

Output

json
{
  "images": [
    {
      "url": "https://v3b.fal.media/files/...",
      "content_type": "image/png",
      "file_name": "output.png",
      "width": 1024,
      "height": 1024
    }
  ]
}

Using the Queue API

For production workloads or longer-running edits, submit requests asynchronously and retrieve results via webhook or polling.

javascript
// Submit
const { request_id } = await fal.queue.submit("openai/gpt-image-2/edit", {
  input: {
    prompt: "...",
    image_urls: ["https://your-image-url.com/photo.png"],
  },
  webhookUrl: "https://your-server.com/webhook",
});

// Check status
const status = await fal.queue.status("openai/gpt-image-2/edit", {
  requestId: request_id,
  logs: true,
});

// Fetch result
const result = await fal.queue.result("openai/gpt-image-2/edit", {
  requestId: request_id,
});

File Inputs

The endpoint accepts image URLs or base64 data URIs. For images that are not publicly accessible, upload them first using the fal storage API:

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

const file = new File([imageBuffer], "photo.png", { type: "image/png" });
const url = await fal.storage.upload(file);

// Use the returned URL as image_urls[0] or mask_image_url

The client will also auto-upload binary objects (File, Blob, Buffer) if you pass them directly.

Use Cases

Product photo editing -- Swap backgrounds, adjust lighting, or update props in product photography without reshooting.

UI and design asset updates -- Edit screenshots, mockups, or design files by describing the change in plain text.

Portrait and photo retouching -- Adjust clothing, environment, or background details while keeping the subject untouched via masking.

Batch content variation -- Generate multiple edited variants of the same base image at different quality settings for A/B testing.

Interactive editing tools -- Use streaming mode to show real-time progress in editing UIs, reducing perceived wait time.

If you want to learn more visit our blog & our gpt image 2 page

How masks work

A mask image is a black-and-white PNG where:

• White pixels indicate regions the model is allowed to edit
• Black pixels indicate regions that must be preserved exactly

The mask must match the dimensions of the input image. If no mask is provided, the model decides which parts of the image to change based on the prompt alone.

Differences from the text-to-image endpoint