Edit & combine images

Upload one or more images and change or merge them with a prompt.

Not writing code? See Generate images in your own tools.

POST/v1/images/editsShared parameters

Before you start

You need	Details
API key	Create one in the OfoxAI console and replace `YOUR_OFOX_API_KEY` in the code
Environment	cURL needs `jq` to decode the image; Python needs `pip install openai`; Node.js 18 or later, no dependencies
Images	Put an `input.png` in the current directory; for combining images, add an `input2.png` too. PNG or JPEG, ≤ 15 MB each
Timeout	Set your client timeout to 600 seconds. High quality, large sizes or editing can take several minutes

Values used in the code

API URLhttps://api.ofox.ai/v1

Model IDopenai/gpt-image-2.5-sunburstThe samples use flare; sunburst is recommended for editing

API keyReplace YOUR_OFOX_API_KEY in the code with your key

Python depspip install openai

Edit an image

Every sample below was run verbatim. The result is saved as output.png in the current directory.

cURL

Terminal


curl -s https://api.ofox.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_OFOX_API_KEY" \
  -F "model=openai/gpt-image-2.5-flare" \
  -F "image=@input.png" \
  -F "prompt=Replace the background with a wooden table, keep the subject unchanged" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

Python

edit.py


import base64
from openai import OpenAI
 
client = OpenAI(
    api_key="YOUR_OFOX_API_KEY",  # replace with your key
    base_url="https://api.ofox.ai/v1",
)
 
result = client.images.edit(
    model="openai/gpt-image-2.5-flare",
    image=open("input.png", "rb"),
    prompt="Replace the background with a wooden table, keep the subject unchanged",
    quality="low",
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
print("Saved output.png")

Node.js

edit.mjs


// Node.js 18+, no dependencies to install
import { readFileSync, writeFileSync } from "node:fs";
 
const form = new FormData();
form.append("model", "openai/gpt-image-2.5-flare");
form.append("image", new Blob([readFileSync("input.png")], { type: "image/png" }), "input.png");
form.append("prompt", "Replace the background with a wooden table, keep the subject unchanged");
form.append("quality", "low");
 
const res = await fetch("https://api.ofox.ai/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OFOX_API_KEY", // replace with your key
  },
  body: form,
});
 
const json = await res.json();
if (!res.ok) throw new Error(JSON.stringify(json));
writeFileSync("output.png", Buffer.from(json.data[0].b64_json, "base64"));
console.log("Saved output.png");

If you omit size, the model picks the output size, which may differ from the original. To keep the original size, pass it explicitly, e.g. size=1024x1024.

Writing the prompt

Say two things clearly: what to change, and what to keep.

Use case	Example prompt
Edit one image	Replace the background with a wooden tabletop and keep the subject unchanged
Combine images	Put the subject of the first image on the background of the second image

With several images, refer to them in upload order as “the first image” and “the second image”. To change only a small part of the image, Inpainting is more reliable.

Combine several images

Send several reference images at once. Upload order is what “the first image” and “the second image” in your prompt refer to. Put input.png and input2.png in the current directory.

cURL

Terminal


# Up to 16 images per request, ≤ 15 MB each
curl -s https://api.ofox.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_OFOX_API_KEY" \
  -F "model=openai/gpt-image-2.5-flare" \
  -F "image[]=@input.png" \
  -F "image[]=@input2.png" \
  -F "prompt=Place the subject of the first image onto the background of the second" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

Providers

You don’t need to pin a provider. For all three models, both Azure and OpenAI serve the edit endpoint, and the gateway routes requests automatically.

If you have content moderation requirements you can select a provider, but the edit endpoint only accepts the X-OfoxAI-Provider-Type header; extra_body in the form is ignored. Once a provider is selected, requests will not fall back to another provider if it is unavailable. See Selecting a provider.

Parameter values

Parameters specific to the edit endpoint. model, n, output_format and the rest work as in text to image — see Text to image · Parameter values.

Required

imagerequiredfileform

The image to edit. For several images, repeat the field as image[]; with the Python SDK, pass a list.

▸ Details

Reference images are billed as tokens too: a 1024×1024 reference image measured 1,024 input tokens, which is why editing costs more than text to image at the same size.

▶Advanced · 1X-OfoxAI-Provider-TypeExpand

X-OfoxAI-Provider-Typestringheader· valuesazure_foundryopenai

Usually not needed — the gateway routes automatically. Use it only to pin a specific provider.

Upload limits

Item	Limit
Each reference image	≤ 15 MB
Whole request	≤ 50 MB
Number of images	No gateway limit; keep it to 16 or fewer
Format	PNG, JPEG

The model scales reference images to about 1024 px. Files over 5 MB only make the upload slower; they do not improve the result.

Common errors

Error	Cause	Fix
`Invalid image file or mode`	The uploaded image is not a standard PNG or JPEG	Re-export as PNG or JPEG
`Invalid file 'image[0]': unsupported mimetype`	The uploaded file is not an image	Upload a PNG, JPEG or WebP image
`does not support the 'input_fidelity' parameter`	`input_fidelity` was sent	Remove it; this family always processes reference images at high fidelity
`moderation_blocked`	The prompt or reference image was blocked by the upstream safety system	Change the prompt or reference image and try again
`provider_type_unavailable`	The provider you pinned manually doesn’t serve this model	Remove the `X-OfoxAI-Provider-Type` header
`Invalid size`	The size you passed breaks one of the four rules	See Size
`404 model_not_found`	Model ID misspelled or wrong case	Copy the model ID from this page

For other errors, see the full error table.

Official docs

OpenAI’s docs describe behavior when you call OpenAI directly. When you call through OfoxAI, the measured results in these pages take precedence. For example, you don’t need to pin a provider for editing.