Image edits
Compatible with OpenAI Images Edit. Generates a new image from reference images and an instruction.
POST
https://api.codingrouter.ai/v1/images/edits| Model | Token group | Reference images |
|---|---|---|
gpt-image-2, gpt-image-2.5 | gpt_image | 1 to 16, optional mask |
grok-imagine-image-2.0 | grok | 1, $0.004 per call |
Authentication
Authorization: Bearer <token>
Request format
Use either of two forms:
multipart/form-data: upload image files. Recommended for large reference images, because base64 in JSON makes the request body about one third larger.application/json: pass images as a URL ordata:base64.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | See the table above |
prompt | string | Yes | Edit instruction, up to 32000 characters |
image | file | Yes | Form upload: image for one, several image[] for multiple |
images | array | Yes | JSON form (GPT Image): [{"image_url": "https://... or data:..."}] |
image | string | Yes | JSON form (Grok): base64 starting with data: |
mask | file | No | GPT Image mask: PNG, same size as the first reference image, transparent areas are the parts to redraw |
size | string | No | Same as Image generation |
quality | string | No | Same as image generation |
n | integer | No | Number of images GPT Image generates, 1 to 10 |
output_format, output_compression, background, moderation | No | Same as image generation | |
input_fidelity | string | No | gpt-image-2.5 only |
stream | boolean | No | GPT Image: when true, returns SSE, and the result is in the image_edit.completed event |
Reference image requirements: PNG, JPEG or WebP, at most 50 MB each. Image URLs in JSON must be publicly reachable, and the server downloads them within 60 seconds.
Request example
bash
curl https://api.codingrouter.ai/v1/images/edits \
-H "Authorization: Bearer $CODINGROUTER_KEY" \
-F model=gpt-image-2 \
-F prompt="Change the background to a seaside sunset, keep the person unchanged" \
-F size=1024x1536 \
-F quality=medium \
-F image=@src.pngbash
curl https://api.codingrouter.ai/v1/images/edits \
-H "Authorization: Bearer $CODINGROUTER_KEY" \
-F model=gpt-image-2.5 \
-F prompt="Put the hat from the second image on the person in the first image" \
-F "image[]=@person.png" \
-F "image[]=@hat.png" \
-F mask=@mask.pngbash
curl https://api.codingrouter.ai/v1/images/edits \
-H "Authorization: Bearer $CODINGROUTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "Change the background to a seaside sunset, keep the person unchanged",
"size": "1024x1024",
"quality": "low",
"images": [
{"image_url": "https://example.com/src.png"},
{"image_url": "data:image/jpeg;base64,<image base64>"}
]
}'python
import base64
from openai import OpenAI
client = OpenAI(base_url="https://api.codingrouter.ai/v1", api_key="sk-your-token", timeout=300)
result = client.images.edit(
model="gpt-image-2",
prompt="Change the background to a seaside sunset, keep the person unchanged",
image=[open("src.png", "rb")], # for several reference images, pass several files
size="1024x1536",
quality="medium",
)
with open("out.png", "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))js
import fs from "node:fs";
import OpenAI, { toFile } from "openai";
const client = new OpenAI({
baseURL: "https://api.codingrouter.ai/v1",
apiKey: process.env.CODINGROUTER_KEY,
timeout: 300_000,
});
const result = await client.images.edit({
model: "gpt-image-2",
prompt: "Change the background to a seaside sunset, keep the person unchanged",
image: await toFile(fs.createReadStream("src.png"), "src.png", { type: "image/png" }),
size: "1024x1536",
quality: "medium",
});
fs.writeFileSync("out.png", Buffer.from(result.data[0].b64_json, "base64"));Grok Imagine
bash
# Form
curl https://api.codingrouter.ai/v1/images/edits \
-H "Authorization: Bearer $CODINGROUTER_KEY" \
-F model=grok-imagine-image-2.0 \
-F prompt="Change the apple to a green apple, keep everything else unchanged" \
-F image=@src.jpg
# JSON
curl https://api.codingrouter.ai/v1/images/edits \
-H "Authorization: Bearer $CODINGROUTER_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "grok-imagine-image-2.0", "prompt": "Change the apple to a green apple, keep everything else unchanged", "image": "data:image/jpeg;base64,<original image base64>"}'Response example
Same as Image generation:
json
{
"created": 1794383305,
"data": [{"b64_json": "<base64 image data>"}],
"output_format": "png",
"size": "1024x1536",
"usage": {"input_tokens": 211, "output_tokens": 1372, "total_tokens": 1583}
}Errors
| Status | Common cause |
|---|---|
| 400 | Size does not follow the rules, quality not supported, wrong image format or too large, mask size differs from the original image, image URL download failed, response_format is url |
| 413 | Request exceeds 256 MB |
| 429 | Concurrency is full, retry later |
| 502 | Upstream generation failed, can retry |
