# GPT Image 2 · Image Editing

Edit and enhance images with GPT Image 2 · Image Editing from fal through one Spiral API key. Edits images from a text instruction with OpenAI's GPT Image 2, using up to 16 reference images and an optional mask for the area. It runs in the background and returns images. Pay as you go, with no subscription.

- Provider: fal
- Category: Image
- Runs: In the background
- Returns: image
- Released: 2026-04-20
- Tool id: `fal` / `openai/gpt-image-2/edit`
- Page: https://spiral.ai/tools/fal/openai/gpt-image-2/edit

## Pricing

$0.188 per 4:3 image at high quality ($0.00572 low, $0.0475 medium). At high: $0.24 square, $0.274 square HD, $0.135 16:9. Auto quality or size: the price of the one chosen for the request. Prompt: $6.50 per 1M tokens. Input images: $0.0106 each at 1024×1024.

## Limits

- Longest queue wait: 1 hour
- Run deadline: 30 minutes
- Longest run, end to end: 225 minutes
- Largest inline input: 1 MB
- Largest input file: 2 GB
- Largest output: 5 GB

## Input

| Field | Kind | Allowed | Default | Description |
| --- | --- | --- | --- | --- |
| `prompt` (required) | text |  | — | The prompt for image generation |
| `image_urls` (required) | URLs or files |  | — | The URLs of the images to use as a reference for the generation. A maximum of 16 images are allowed, each at most 25 MB (25,000,000 bytes). |
| `image_size` | JSON |  | auto | The size of the generated image. 'auto' matches the first image's size, except with image_passthrough, where it returns about 1.5 MP (e.g. 1536x1024); set width and height to keep the reference size. Explicit sizes need both sides as multiples of 16, a longest edge of at most 3840 px, an aspect ratio of at most 3:1, and 655,360 to 8,294,400 pixels. |
| `background` | one of | auto, opaque | auto | Background for the generated image |
| `quality` | one of | auto, low, medium, high | high | Quality for the generated image. Use 'auto' to let the model pick the best quality for the prompt. |
| `num_images` | number (whole) | 1 to 10 | 1 | Number of images to generate |
| `output_format` | one of | jpeg, png, webp | png | Output format for the images |
| `output_compression` | number (whole) | 0 to 100 | — | Compression level from 0 to 100. Only supported when output_format is 'jpeg' or 'webp'. |
| `image_passthrough` | true or false |  | false | Send reference images and masks without resizing or re-encoding, and return the provider's original image bytes and format. Requests use the direct OpenAI API. Masks must be PNGs with an alpha channel: transparent regions are edited, and dimensions must match the first reference. |
| `mask_url` | URL or file |  | — | Mask image URL. Standard processing treats white as edit and black as keep. With image_passthrough or provider_options, supply an OpenAI-native PNG alpha mask: transparent regions are edited, and dimensions must match the first reference. Known provider issue: at non-square sizes the masked area can come back as a black box; square images and masks edit correctly. The mask guides the edit but is not a hard boundary: the model redraws the whole image, so unmasked areas (faces, text) can change; composite the output over the original to keep them exactly. |

## Example

```bash
curl https://api.spiral.ai/v1/runs \
  -H "Authorization: Bearer $SPIRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "provider": "fal",
    "model": "openai/gpt-image-2/edit",
    "input": {
      "prompt": "Same workers, same beam, same lunch boxes - but they'\''re all on their phones now. One is taking a selfie. One is on a call looking annoyed. Same danger, new…",
      "image_urls": [
        "<image_urls>"
      ]
    }
  }'
```

Try it in the Playground: https://spiral.ai/start?provider=fal&model=openai%2Fgpt-image-2%2Fedit

## Common questions

### GPT Image 2 · Image Editing

**How much does GPT Image 2 · Image Editing cost?**

$0.188 per 4:3 image at high quality ($0.00572 low, $0.0475 medium). At high: $0.24 square, $0.274 square HD, $0.135 16:9. Auto quality or size: the price of the one chosen for the request. Prompt: $6.50 per 1M tokens. Input images: $0.0106 each at 1024×1024. You pay as you go from one Spiral balance, with no subscription, and a failed run is not charged.

**How do I use GPT Image 2 · Image Editing through an API?**

Send `POST /v1/runs` with `"provider": "fal"`, `"model": "openai/gpt-image-2/edit"` and the input fields on this page, using one Spiral API key. It runs in the background: poll the run, or name a webhook to be told when it finishes.

**Do I need an account with fal to use GPT Image 2 · Image Editing?**

No. Spiral runs it on its own fal account and charges your Spiral balance.

**Can my AI agent use GPT Image 2 · Image Editing?**

Yes. Agents find and run it through Spiral's MCP server, CLI or agent skill, with the same API key.

