AI Image Editing API: Inpainting, Variations & Reference Generation
You've generated a product image but the background needs to change — or the lighting is off and a full re-generation risks losing everything that worked. Calling a fresh text-to-image generation rarely reproduces the same composition. What you need is an image editing API: pass the original, specify the change, and get back a refined output.
GenRelay exposes two distinct editing workflows. GPT-image-2 accepts an existing image plus a natural-language instruction and returns an edited version. Nano Banana Pro supports reference-guided generation — provide a reference image and a prompt to steer composition, style, or content while anchoring to visual inputs. This guide shows how each works, with copy-paste Python code and exact cost numbers.
What Can an Image Editing API Actually Do?
Image editing via API covers three practical workflows:
- Instruction-based editing (GPT-image-2): send an image + text instruction ("remove the background", "change the shirt to blue") and get back an edited version without supplying explicit mask coordinates.
- Reference-guided generation (Nano Banana Pro): provide a reference image to anchor style, face, or product composition while generating new content around it.
- Variations: generate multiple outputs from the same seed image for A/B testing product visuals, each with slight creative variance.
These workflows are distinct from text-to-image generation. Edit requests go to a separate endpoint (/v1/images/edits), and the model's input includes image data rather than just a text prompt. The key difference from starting fresh: the model understands what to preserve versus what to change.
How Do I Authenticate with the GenRelay Image Editing API?
Authentication uses a Bearer token in the Authorization header — the same key used for all GenRelay endpoints. Retrieve your API key from the GenRelay console.
import requests
import base64
import os
API_KEY = os.environ["GENRELAY_API_KEY"]
BASE_URL = "https://genrelay.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
Store your key in an environment variable rather than hardcoding it. See the image API authentication guide for key rotation and error code reference.
How Do I Edit an Image Using GPT-image-2?
GPT-image-2 supports instruction-based editing via the /v1/images/edits endpoint. The request uses multipart/form-data — you send the original image as a file alongside the prompt.
Step 1 — Submit the edit request:
import requests
import os
API_KEY = os.environ["GENRELAY_API_KEY"]
def edit_image(image_path: str, instruction: str, n: int = 1, size: str = "1024x1024") -> list[str]:
with open(image_path, "rb") as image_file:
response = requests.post(
"https://genrelay.ai/v1/images/edits",
headers={"Authorization": f"Bearer {API_KEY}"},
files={"image": (image_path, image_file, "image/png")},
data={
"model": "gpt-image-2",
"prompt": instruction,
"n": n,
"size": size
}
)
response.raise_for_status()
return [item["url"] for item in response.json()["data"]]
urls = edit_image(
"product_original.png",
"Replace the background with a clean white studio backdrop. Keep the product unchanged.",
n=1
)
print(f"Edited image URL: {urls[0]}")
Step 2 — Download and save the output:
from pathlib import Path
def download_image(url: str, output_path: str) -> None:
img_data = requests.get(url).content
Path(output_path).write_bytes(img_data)
print(f"Saved to {output_path}")
download_image(urls[0], "product_edited.png")
The prompt field accepts natural-language instructions. GPT-image-2 interprets the instruction in context of the input image — prompts like "make the background transparent", "change the color of the object to red", or "add a subtle drop shadow beneath the product" work without needing explicit mask coordinates.
Generating variations — pass n greater than 1 to get multiple edited outputs in a single call:
variation_urls = edit_image(
"hero_shot.png",
"Relight with warm golden-hour sunlight from the left side.",
n=4
)
At $0.014 per image, four variations cost $0.056 — practical for A/B testing marketing visuals before a campaign launch.
How Do I Use Nano Banana Pro for Reference-Guided Generation?
Nano Banana Pro handles reference guidance through the standard generation endpoint with an additional image parameter (base64-encoded). This approach anchors the generation to the visual characteristics of the reference image — useful when you need to maintain subject identity across multiple generated scenes.
import requests
import base64
import os
API_KEY = os.environ["GENRELAY_API_KEY"]
def reference_generate(reference_path: str, prompt: str, size: str = "1024x1024") -> str:
with open(reference_path, "rb") as f:
ref_b64 = base64.b64encode(f.read()).decode("utf-8")
response = requests.post(
"https://genrelay.ai/v1/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"model": "nano-banana-pro",
"prompt": prompt,
"image": ref_b64,
"size": size,
"n": 1
}
)
response.raise_for_status()
return response.json()["data"][0]["url"]
url = reference_generate(
"brand_logo_reference.png",
"The logo centered on a matte black business card, professional photography, macro lens"
)
print(f"Reference-guided output: {url}")
Reference guidance works best when the reference image is clean and well-lit. Cluttered or low-resolution references produce weaker anchoring — the model may drift toward a generic interpretation of the prompt.
For 4K output (print-ready, large-format advertising), set "size": "4096x4096". Nano Banana Pro pricing: 1K and 2K at $0.030 per image, 4K at $0.042. Higher resolution is worthwhile when the output goes to print or large-screen digital.
What Does Image Editing via API Cost?
| Model | Endpoint | Price | Best for |
|---|---|---|---|
| GPT-image-2 | /v1/images/edits |
$0.014 / image | Instruction-based editing, background changes, object recoloring |
| Nano Banana Pro | /v1/images/generations |
$0.030 (1K–2K) / $0.042 (4K) | Reference-guided generation, style anchoring |
| Nano Banana 2 | /v1/images/generations |
$0.020 (1K) / $0.036 (4K) | Reference generation at lower cost per image |
Workload math — 500 product image edits per day:
- GPT-image-2 edits: 500 × $0.014 = $7.00/day (~$210/month)
- Nano Banana Pro reference at 1K: 500 × $0.030 = $15.00/day (~$450/month)
- Nano Banana 2 reference at 1K: 500 × $0.020 = $10.00/day (~$300/month)
For pure editing tasks — background swap, recoloring, lighting adjustment — GPT-image-2 at $0.014 is the most cost-efficient path. For maintaining strict visual identity (brand assets, product design consistency, face anchoring), Nano Banana Pro or Nano Banana 2's reference-guided approach gives you compositional control that instruction-only editing cannot match.
See the multi-model image API comparison for a full quality and cost breakdown across all three GenRelay image models.
FAQ
Does GPT-image-2 support transparent background generation?
Yes. Set the prompt to "transparent background" or "remove the background" and request PNG output. The returned image will include an alpha channel where the background was removed.
Can I edit an image that wasn't generated on GenRelay?
Yes. The edit endpoint accepts any image file — it does not need to have originated from GenRelay. Any valid PNG, JPEG, or WebP image within the size limit is accepted.
What's the maximum input image size for edits?
Keep input images under 4MB for reliable processing. For larger source files, resize to 2048px on the longest side before sending to avoid timeout or rejection errors.
Does Nano Banana Pro support mask-based inpainting?
As of September 2026, the GenRelay Nano Banana Pro endpoint does not expose explicit mask-based inpainting. Use GPT-image-2 for instruction-based edits where you describe the change in natural language. Use Nano Banana Pro when you want to anchor composition to a reference image rather than make pixel-level targeted edits.
How many edit requests can I run concurrently?
Standard accounts support up to 10 concurrent image requests. For batch editing workflows — processing hundreds of product images — use a semaphore-limited async queue rather than firing all requests simultaneously. See the batch image generation guide for concrete asyncio patterns.
Summary
| Task | Model | Endpoint | Approx. cost |
|---|---|---|---|
| Background replacement | GPT-image-2 | /v1/images/edits |
$0.014/image |
| Object recoloring | GPT-image-2 | /v1/images/edits |
$0.014/image |
| A/B variation set (4 images) | GPT-image-2 | /v1/images/edits |
$0.056 |
| Style anchoring with reference | Nano Banana Pro | /v1/images/generations |
$0.030 (1K) |
| 4K print-quality reference gen | Nano Banana Pro | /v1/images/generations |
$0.042 |
Instruction-based editing with GPT-image-2 handles most routine editing tasks at the lowest per-image cost. When you need strict visual identity — anchoring a face, product silhouette, or brand aesthetic across generated scenes — reference-guided generation with Nano Banana Pro gives you the compositional control that instruction editing alone cannot reliably provide.