Edit an image using a model

Edit an image using a model in a format that is compatible with the OpenAI API. Accepts a multipart/form-data request with an input image reference in the url field and a text prompt. Optionally, provide mask_image to restrict editing to specific areas. The request body is limited to 16 MiB. Inline base64 data URIs in url or mask_image are limited to 12 MiB decoded each; exceeding either limit returns HTTP 413.

post

Authorizations

AuthorizationstringRequired

Please provide header value as 'Bearer ' and don't forget to add 'Bearer' HTTP Authorization Scheme before the token.

Body

urlstring · uriRequired

URL of the image to edit. Supported formats: public HTTP/HTTPS URLs or base64 data URLs (e.g. data:image/png;base64,...). If a mask is not provided, the model will use the entire image as the area to edit. One input image per request. It must be at least 64 pixels on each side, and neither dimension may exceed the other by more than 8×; any other image is rejected with a 400 Bad Request.

promptstring · max: 1000Required

A text description of the desired image(s). Maximum length is 1000 characters.

mask_imagestring · Data URIOptional

A base64-encoded mask image in data:image/png;base64,<encoded-data> format. Fully transparent areas (alpha = 0) indicate where the image should be edited. Must have the same dimensions as the input image.

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

modelstringRequired

ID of the model to use. Please check /v1/models for available models.

ninteger · min: 1 · max: 10Optional

The number of images to generate. Defaults to 1. The model also limits the total pixels one request may produce, n times width times height: 12582912 for FLUX.2-klein-4B (for example three 2048x2048 images). A request over that total-pixel limit is rejected with a 400 Bad Request; a width or height above 8192 pixels is rejected with a 413 Payload Too Large.

Default: 1

sizestringOptional

The size of the generated images, in "widthxheight" format, for example "1024x1024". If omitted, the output keeps the input image's aspect ratio and size, scaled down only as far as the limits below and the per-request pixel limit (see n) require. Width and height from 64 through 2048 pixels (inclusive) are accepted. Values from 2049 through 8192 are rejected with a 400 Bad Request; a width or height above 8192 pixels is rejected with a 413 Payload Too Large. The bounds are checked before rounding, so a side outside them is rejected, not rounded into range. Each side of the output is then rounded down to the nearest multiple of 16, whether size is provided ("1000x1000" returns a 992x992 image) or auto-fitted.

Pattern: ^\d+x\d+$

output_formatstringOptional

The file format of the generated image. Currently png (the default), jpeg, jpg (the same as jpeg) and webp; more formats may be added. A value that is not supported is rejected with a 400 Bad Request.

Default: png

userstringOptional

A unique identifier representing your end-user.

Responses

200

Successful operation

application/json

400

The request was rejected before it reached a model. The message names the field at fault.

application/json

413

The request body, an inline base64 media payload, or the number of content parts in a single message, query, or document exceeds a documented limit, or a requested image's width or height is above the maximum supported size. Pass large media as a remote http(s) URL instead of inline base64 - a remote URL is fetched directly by the model and does not count against the request body size.

application/json

429

Rate limit exceeded. This response carries no Retry-After header, so back off exponentially and watch X-RateLimit-Remaining-Requests on successful responses to slow down before reaching the limit. Limits are contract-specific.

application/json

500

The request failed on our side. It may or may not have been carried out, so a retry is safe for idempotent calls.

application/json

529

The platform is temporarily overloaded and is shedding load to stay stable. Retry after the number of seconds indicated by the Retry-After header. This is unrelated to your contract's rate limits.

application/json

post/v1/images/edits

POST /v1/images/edits HTTP/1.1
Host: openai.inference.de-txl.ionos.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 209

{
  "model": "black-forest-labs/FLUX.2-klein-4B",
  "prompt": "Invert the colors in the input image",
  "n": 1,
  "size": "1024x576",
  "url": "https://www.ionos.de/newsroom/wp-content/uploads/2026/01/Red-Hat_IONOS-1024x576.png"
}

{
  "created": 1,
  "data": [
    {
      "url": "text",
      "b64_json": "text",
      "revised_prompt": "text"
    }
  ]
}