> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/api-reference/ai/ai-model-hub/images/create-image-edit.md).

# Create image edit

Edit an existing image given a prompt and an optional mask, following the OpenAI Images API wire format. Send the request in one of two forms:

* `multipart/form-data`: upload the image bytes in `image`, and optionally `mask`.
* `application/json`: reference the image in `images`, and optionally `mask`, as either a remote HTTP or HTTPS URL or an inline base64 `data:` URL.

The JSON form uses `images` (an array) where the multipart form uses `image`.

```json
{"openapi":"3.0.3","info":{"title":"IONOS CLOUD - OpenAI compatible AI Model Hub API","version":"1.0.0"},"tags":[{"name":"Images","description":"Generate and edit images following the OpenAI Images API."}],"servers":[{"url":"https://openai.inference.de-txl.ionos.com","description":"Berlin"}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Please provide header value as 'Bearer <token>' and don't forget\nto add 'Bearer' HTTP Authorization Scheme before the token.\n"}},"schemas":{"ImageEditRequest":{"type":"object","properties":{"url":{"type":"string","description":"The image to edit, given by reference instead of uploaded: an HTTP or HTTPS URL or a base64 data URL. Accepted as an alternative to `image` for compatibility with earlier versions of this API. Either this or `image` is required, and sending both is rejected."},"prompt":{"type":"string","description":"Text description of the desired edit.","minLength":1},"mask_image":{"type":"string","description":"The mask, given by reference instead of uploaded, in the same forms as `url`. Accepted as an alternative to `mask`."},"model":{"type":"string","description":"ID of the model to use.","minLength":1},"n":{"type":"integer","minimum":1,"maximum":10,"description":"Number of edited images to generate, at most 10. A larger value is rejected with a\n413. A model may also limit the total pixels one request may produce. See `size`.\nWhen omitted, the model chooses.\n"},"size":{"$ref":"#/components/schemas/ImageSize"},"output_format":{"$ref":"#/components/schemas/ImageOutputFormat"},"image":{"type":"string","format":"binary","description":"The image to edit, uploaded as a file part. Must be a PNG, JPEG, or WebP image of at most 10 MiB. A larger file is rejected with a 413. Either this or `url` is required, and sending both is rejected. Which images a model can edit (for example a minimum size or aspect ratio) is model-specific. An image outside a model's limits is rejected with a 400 whose message states the limit."},"mask":{"type":"string","format":"binary","description":"An additional image whose transparent areas indicate where to edit `image`. At\nmost 10 MiB. Whether the mask must match the dimensions of `image` is\nmodel-specific.\n"},"response_format":{"type":"string","description":"Format of the returned images. `b64_json` returns the image data inline and is\nthe only format this API serves. Images are not published at a fetchable address,\nso OpenAI's `url` is rejected with a 400.\n","enum":["b64_json"],"default":"b64_json"}},"required":["model","prompt"],"description":"Request payload for editing an existing image. Sent as `multipart/form-data`.\nThe source image is given either as the binary file part `image`, which is the\nOpenAI shape, or by reference as the text field `url`. The mask follows the\nsame pair, `mask` or `mask_image`, and must be given the same way the image\nwas: an uploaded mask alongside a referenced image, or the reverse, is\nrejected rather than silently dropped.\n\nExactly one of `image` or `url` is required. Sending neither, or both, is\nrejected with a 400 whose message names both fields.\n"},"ImageSize":{"type":"string","description":"Size of the generated images as `WIDTHxHEIGHT` in pixels, for example `1024x1024`. A\nside smaller than 1 or larger than 8192 pixels is rejected with a 413.\n\nWithin that, the sizes served are model-specific: a model may accept only a range of\nsizes, round each side to a step of its own, and limit the pixels one request may\nproduce (`n` times width times height). A request outside a model's limits is\nrejected with a 400 whose message states the limit.\n\nWhen omitted, the model chooses the size.\n"},"ImageOutputFormat":{"type":"string","description":"File format of the returned image, for example `png` or `jpeg`. Distinct from\n`response_format`, which controls how the image is delivered rather than what it\nis encoded as. Supported formats are model-specific. An unsupported value is rejected\nwith a 400 whose message states the supported formats.\n"},"ImageEditJSONRequest":{"type":"object","description":"JSON request body for editing an image. Uses `images` (an array of references) in place\nof the multipart `image` upload. Send this with `Content-Type: application/json`.\n","required":["model","images","prompt"],"properties":{"model":{"type":"string","description":"ID of the model to use.","minLength":1},"images":{"type":"array","description":"Input image references to edit. At most 16. More are rejected with a 413. Within\nthat, how many images a model accepts, and which ones, is model-specific. A request\noutside a model's limits is rejected with a 400 whose message states the limit.\n","minItems":1,"maxItems":16,"items":{"$ref":"#/components/schemas/ImageRef"}},"mask":{"$ref":"#/components/schemas/ImageRef"},"prompt":{"type":"string","description":"Text description of the desired edit.","minLength":1},"n":{"type":"integer","description":"Number of edited images to generate, at most 10. A larger value is rejected with a\n413. A model may also limit the total pixels one request may produce. See `size`.\nWhen omitted, the model chooses.\n","minimum":1,"maximum":10},"size":{"$ref":"#/components/schemas/ImageSize"},"output_format":{"$ref":"#/components/schemas/ImageOutputFormat"},"response_format":{"type":"string","description":"Format of the returned images. `b64_json` returns the image data inline and is\nthe only format this API serves. Images are not published at a fetchable address,\nso OpenAI's `url` is rejected with a 400.\n","enum":["b64_json"],"default":"b64_json"}}},"ImageRef":{"type":"object","description":"Reference to an input image. Provide the image either as a public HTTP or HTTPS URL or\nas an inline base64 `data:` URL (for example `data:image/png;base64,iVBORw0KGgo...`).\n\nA remote URL must be reachable from the internet, not only from your network, the same\nas for the image inputs on `/v1/chat/completions` and `/v1/embeddings`.\n","required":["image_url"],"properties":{"image_url":{"type":"string","description":"A fully qualified HTTP or HTTPS URL, or a base64-encoded `data:` URL.","minLength":1}}},"ImageResponse":{"type":"object","description":"Response containing one or more generated or edited images.","required":["created","data"],"properties":{"created":{"type":"integer","description":"Unix timestamp (in seconds) of when the images were created."},"data":{"type":"array","description":"One `ImageData` object per generated image.","items":{"$ref":"#/components/schemas/ImageData"}}}},"ImageData":{"type":"object","description":"A single generated image.","properties":{"url":{"type":"string","description":"Reserved for OpenAI compatibility and never returned by this API, which serves\n`b64_json` only. Read `b64_json` instead.\n","format":"uri"},"b64_json":{"type":"string","description":"Base64-encoded image data. Present when `response_format` is `b64_json`."},"revised_prompt":{"type":"string","description":"The prompt actually used to generate the image, if the model revised it."}}},"Error":{"type":"object","description":"Error response.","properties":{"httpStatus":{"type":"integer","description":"HTTP status code of the operation as specified by RFC 7231."},"messages":{"type":"array","description":"List of error messages.","items":{"type":"object","properties":{"errorCode":{"type":"string","description":"Stable, machine-readable classification of the failure. Branch on this\nrather than on `message`, which is meant for humans and may be reworded.\n\nClient errors, safe to act on:\n\n- `VALIDATION_ERROR` (400) a field is missing, malformed or out of the\n  documented range. The message names the field.\n- `INVALID_JSON` (400) the body is not valid JSON.\n- `INVALID_MULTIPART` (400) the multipart form could not be parsed.\n- `INVALID_TOKEN` (401) the `Authorization` header is larger than 8 KiB.\n  Every other 401 carries one of the authentication codes instead:\n  `paas-auth-1` (the `Authorization` header is missing or does not hold a\n  `Bearer` token), `paas-token-1` (the token was not accepted) or\n  `paas-auth-2` (the token could not be verified as a customer token).\n- `INSUFFICIENT_PRIVILEGES` (403) the token is valid but its contract\n  lacks the privilege required to use this API.\n- `MODEL_NOT_SUPPORTED` (404) the model is unknown. A known model that lacks\n  the capability this endpoint or request needs is rejected with a 400\n  `VALIDATION_ERROR` naming the models that have it.\n- `ROUTE_NOT_FOUND` (404) no endpoint exists at the requested path.\n- `METHOD_NOT_ALLOWED` (405) the endpoint exists but does not accept the\n  HTTP method used.\n- `RESOURCE_LIMIT_ERROR` (413) the request exceeds a documented size or\n  count limit.\n- `RATE_LIMIT_EXCEEDED` (429) the contract's rate limit is exhausted.\n  Wait the number of seconds in `Retry-After` before retrying.\n- `SERVICE_OVERLOADED` (503) too many large requests are already being\n  handled at once. Applies only above a size threshold, or to a request\n  sent with chunked transfer encoding. An ordinary request is never\n  refused this way. Retry after the interval in `Retry-After`.\n- `CLIENT_DISCONNECTED` (499) you closed the connection before the\n  response was ready. You never receive this code, since the connection\n  is already gone. It identifies the request in usage records. Tokens\n  generated before the disconnect are still billed.\n\nThe model refused or could not be reached:\n\n- `UPSTREAM_REJECTED` the model rejected the request. The status is the\n  one it returned, and the message carries its explanation. Usually a 4xx\n  and usually worth fixing rather than retrying. An image or video URL in\n  the request that answers with a client error, such as 404, comes back\n  as 422 with this code: check that the URL exists and is publicly\n  reachable.\n- `UPSTREAM_NOT_IMPLEMENTED` (422) the model understood the request and\n  does not implement part of it. Retrying does not help. The same request\n  may succeed against a different model.\n- `UPSTREAM_UNAVAILABLE` (502) the model could not be reached, or stopped\n  before it finished answering. Retrying is reasonable. A partial answer\n  is never returned in its place, and nothing is billed for it. An image or\n  video URL whose host cannot be reached, times out or answers with a\n  server error comes back this way too.\n- `UPSTREAM_TIMEOUT` (504) the model did not answer within the time allowed\n  for it. The work may have been too expensive:\n  prefer a smaller request or a different model over retrying the same\n  one unchanged.\n\nAn internal error occurred (500). The code identifies where it happened\nand is not a contract to branch on. Treat these alike:\n`CHAT_COMPLETION_ERROR`, `COMPLETION_ERROR`, `EMBEDDING_ERROR`,\n`IMAGE_ERROR`, `RERANK_ERROR`, `RESPONSES_ERROR`, `TRANSCRIPTION_ERROR`,\n`CONVERSION_ERROR`.\n\nNew codes may be added, so treat an unrecognized value as a generic\nfailure of its HTTP status class rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable explanation, intended for logs and for showing to a\ndeveloper. Wording may change between releases, so branch on `errorCode`.\n"}},"additionalProperties":false}}},"required":["httpStatus","messages"],"additionalProperties":false},"OpenAIError":{"type":"object","description":"OpenAI-compatible error response.","required":["error"],"properties":{"error":{"type":"object","description":"The error details.","required":["message","type"],"properties":{"message":{"type":"string","description":"Human-readable explanation of the error."},"type":{"type":"string","description":"Error category, for example `invalid_request_error`."},"code":{"type":"string","description":"Machine-readable sub-classification of `type`. Used by the 529 overload\nresponse to distinguish a per-user throttle (`user_overloaded`) from a\nsystem-wide capacity shortage (`server_overloaded`), so you do not have to\nparse the `message` text.\n"}}}}}},"headers":{"X-RateLimit-Limit-Requests":{"description":"How many requests per interval your contract's rate limit allows for this\nrequest. The value, and the length of the interval, depend on your contract.\nAbsent when no rate-limit check ran, for example on a request refused for a\nmalformed body.\n","schema":{"type":"integer"}},"X-RateLimit-Remaining-Requests":{"description":"How many of those requests are still unused. It counts down from\n`X-RateLimit-Limit-Requests`, never exceeds it, and refills continuously over the\ninterval. Once it reaches 0, slow down: further requests may be refused with a\n429 until it refills. Absent when no rate-limit check ran.\n","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier for this request. Quote it when reporting a problem to support.","schema":{"type":"string"}},"X-Gateway-Version":{"description":"Build version of the API that served the response.","schema":{"type":"string"}},"X-RateLimit-Reset-Requests":{"description":"The time until the rate limit is back at its initial state, with\n`X-RateLimit-Remaining-Requests` equal to the limit again, as a duration such as\n`200ms`, `1.5s` or `6m0s`. Requests refill gradually, so the remaining count\nrises well before then. Absent when no rate-limit check ran.\n","schema":{"type":"string"}}},"responses":{"BadRequest":{"description":"### Bad Request\nThe request sent to the API was malformed.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"### Unauthorized\nThe request is missing authorization information or the authorization information provided are expired.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"### Forbidden\nThe user issuing the request does not have the needed permissions.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"### Not Found\nThe requested model or endpoint does not exist. A model that exists but lacks the\ncapability the request needs is rejected with a 400 instead.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"### Payload Too Large\nThe request exceeds a size limit. The request body is limited to 16 MiB, an inline\nbase64 data URI to 12 MiB decoded, and an uploaded image or mask to 10 MiB. On\n`/v1/chat/completions`, `/v1/embeddings`, and `/v1/rerank`, a message, query, or\ndocument is limited to 2048 content parts. Count limits, such as the number of\ndocuments, are stated with each field. Pass large media as a remote HTTP or HTTPS URL\ninstead of inline base64: a URL does not count against the size limits, though it\nstill counts as a content part.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"### Unprocessable Entity\nThe request was well-formed but contains semantic errors.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"### Too Many Requests\nYour contract's rate limit is exhausted. Wait the number of seconds in `Retry-After`\nbefore retrying, rather than a delay of your own. The OpenAI SDKs do this\nautomatically. Limits are contract-specific.\n","headers":{"X-RateLimit-Limit-Requests":{"$ref":"#/components/headers/X-RateLimit-Limit-Requests"},"X-RateLimit-Remaining-Requests":{"$ref":"#/components/headers/X-RateLimit-Remaining-Requests"},"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"},"Retry-After":{"description":"Seconds to wait before retrying. Other requests under your contract count\nagainst the same limit, so a retry can still be refused.\n","schema":{"type":"integer"}},"X-RateLimit-Reset-Requests":{"$ref":"#/components/headers/X-RateLimit-Reset-Requests"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"### Internal Server Error\nThe request could not be completed because of an internal error. The request was\nnot necessarily rejected, so a retry is safe for idempotent calls. If it persists,\nquote the value of the `X-Request-Id` response header when contacting support.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadGateway":{"description":"### Bad Gateway\nThe model could not be reached, or stopped before it finished answering. No partial\nanswer is returned in its place, and nothing is billed for it. Retrying is\nreasonable. An image or video URL in the request whose host cannot be reached,\ntimes out or answers with a server error is also answered this way.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServiceOverloaded":{"description":"### Service Overloaded (503)\nToo many large requests are already being handled at once. This applies only\nto a request above a size threshold, or one sent with chunked transfer\nencoding. An ordinary-sized request is never refused this way. Always retry\nusing the `Retry-After` header, not a fixed delay, to avoid a synchronized\nretry storm. For sustained traffic in media, keep individual requests small:\npass large media in a JSON body as a remote HTTP or HTTPS URL rather than\ninline base64, and keep a file upload small, for example by sending audio in\na compressed format such as MP3 or Opus. The message gives the advice that\nfits how the request was sent.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"GatewayTimeout":{"description":"### Gateway Timeout\nThe model did not answer within the time allowed for it. The request may\nhave reached the model and may even have been served, so a retry is only safe for\nidempotent calls. Retrying the same request unchanged tends to time out again: the\nwork itself is usually what was too slow, so prefer a smaller request (fewer or\nsmaller images, a shorter prompt, a lower `n`) or a model that can serve it.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Overloaded":{"description":"### Capacity Exhausted (529)\nThe service is temporarily overloaded. This is a non-standard status,\nmatching the convention used by other LLM providers for the same\ncondition: capacity is exhausted, not a client error (429) and not an\noutage (503). `error.code` distinguishes a per-user throttle\n(`user_overloaded`) from a system-wide capacity shortage\n(`server_overloaded`). If you check only the status, treat both\nalike. Always retry using the `Retry-After` header, not a\nfixed delay, to avoid a synchronized retry storm.\n","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIError"}}}}}},"paths":{"/v1/images/edits":{"post":{"operationId":"v1ImagesEditsPost","summary":"Create image edit","description":"Edit an existing image given a prompt and an optional mask, following the OpenAI Images\nAPI wire format. Send the request in one of two forms:\n\n- `multipart/form-data`: upload the image bytes in `image`, and optionally `mask`.\n- `application/json`: reference the image in `images`, and optionally `mask`, as either\n  a remote HTTP or HTTPS URL or an inline base64 `data:` URL.\n\nThe JSON form uses `images` (an array) where the multipart form uses `image`.\n","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ImageEditRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/ImageEditJSONRequest"}}}},"responses":{"200":{"description":"Successful operation.","headers":{"X-RateLimit-Limit-Requests":{"$ref":"#/components/headers/X-RateLimit-Limit-Requests"},"X-RateLimit-Remaining-Requests":{"$ref":"#/components/headers/X-RateLimit-Remaining-Requests"},"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Gateway-Version":{"$ref":"#/components/headers/X-Gateway-Version"},"X-RateLimit-Reset-Requests":{"$ref":"#/components/headers/X-RateLimit-Reset-Requests"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/BadGateway"},"503":{"$ref":"#/components/responses/ServiceOverloaded"},"504":{"$ref":"#/components/responses/GatewayTimeout"},"529":{"$ref":"#/components/responses/Overloaded"}},"tags":["Images"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ionos.com/cloud/api-reference/ai/ai-model-hub/images/create-image-edit.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
