Skip to content

Image edits ​

Compatible with OpenAI Images Edit. Generates a new image from reference images and an instruction.

POSThttps://api.codingrouter.ai/v1/images/edits
ModelToken groupReference images
gpt-image-2, gpt-image-2.5gpt_image1 to 16, optional mask
grok-imagine-image-2.0grok1, $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 or data: base64.

Request parameters ​

ParameterTypeRequiredDescription
modelstringYesSee the table above
promptstringYesEdit instruction, up to 32000 characters
imagefileYesForm upload: image for one, several image[] for multiple
imagesarrayYesJSON form (GPT Image): [{"image_url": "https://... or data:..."}]
imagestringYesJSON form (Grok): base64 starting with data:
maskfileNoGPT Image mask: PNG, same size as the first reference image, transparent areas are the parts to redraw
sizestringNoSame as Image generation
qualitystringNoSame as image generation
nintegerNoNumber of images GPT Image generates, 1 to 10
output_format, output_compression, background, moderationNoSame as image generation
input_fidelitystringNogpt-image-2.5 only
streambooleanNoGPT 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.png
bash
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.png
bash
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 ​

StatusCommon cause
400Size 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
413Request exceeds 256 MB
429Concurrency is full, retry later
502Upstream generation failed, can retry