{"command":{"effect":"write","timeoutSeconds":120,"inputSchema":{"type":"object","description":"Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models.","properties":{"body":{"$ref":"#/definitions/EditImageBodyJsonParam","examples":[{"model":"gpt-image-1.5","prompt":"Add a watercolor effect to this image","images":[{"image_url":"https://example.com/source-image.png"}],"size":"1024x1024","quality":"high"}]}},"required":["body"],"additionalProperties":false,"definitions":{"EditImageBodyJsonParam":{"type":"object","description":"JSON request body for image edits.\n\nUse `images` (array of `ImageRefParam`) instead of multipart `image` uploads.\nYou can reference images via external URLs, data URLs, or uploaded file IDs.\nJSON edits support GPT image models.\n","properties":{"model":{"anyOf":[{"type":"string"},{"type":"string","enum":["gpt-image-1.5","gpt-image-2","gpt-image-2-2026-04-21","gpt-image-2.5-sunburst","gpt-image-2.5-sunburst-2026-09-08","gpt-image-2.5-flare","gpt-image-2.5-flare-2026-09-08","gpt-image-1","gpt-image-1-mini","chatgpt-image-latest"]},{"type":"null"}],"default":"gpt-image-2.5-sunburst","description":"The GPT image model to use for image editing, including `gpt-image-2`, its dated\nsnapshot `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`,\n`gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and\n`gpt-image-2.5-flare-2026-09-08`. Defaults to `gpt-image-2.5-sunburst`.\n\n`gpt-image-1` was shut down on October 23, 2026. Use\n`gpt-image-2.5-sunburst` or `gpt-image-2.5-flare` instead.\n","examples":["gpt-image-2.5-sunburst"]},"images":{"type":"array","minItems":1,"maxItems":16,"description":"Input image references to edit.\nFor GPT image models, you can provide up to 16 images.\n","items":{"$ref":"#/definitions/ImageRefParam"}},"mask":{"$ref":"#/definitions/ImageRefParam"},"markup":{"$ref":"#/definitions/ImageRefParam"},"prompt":{"type":"string","minLength":1,"maxLength":32000,"description":"A text description of the desired image edit.","examples":["Add a watercolor effect and keep the subject centered"]},"n":{"anyOf":[{"type":"integer","minimum":1,"maximum":10},{"type":"null"}],"default":1,"description":"The number of edited images to generate.","examples":[1]},"quality":{"anyOf":[{"type":"string","enum":["low","medium","high","xhigh","max","auto"]},{"type":"null"}],"default":"auto","description":"Output quality for GPT image models. The GPT image models support `low`, `medium`,\nand `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their\n`2026-09-08` snapshots, also support `xhigh` and `max`. Defaults to `auto`.\n","examples":["high"]},"input_fidelity":{"anyOf":[{"type":"string","enum":["high","low"]},{"type":"null"}],"description":"Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports `high` and `low` on `gpt-image-1.5`; `gpt-image-1-mini` supports only `low`. For `gpt-image-2`, omit this parameter. Defaults to `low` on supported models."},"size":{"anyOf":[{"type":"string"},{"type":"string","enum":["auto","1024x1024","1536x1024","1024x1536"]},{"type":"null"}],"default":"auto","description":"The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing.","examples":["1024x1024"]},"safety_identifier":{"type":["string","null"],"maxLength":128,"description":"A stable identifier for an end user in your organization, used for safety monitoring and abuse detection. Hash a username or email address to avoid sending identifying information. A non-empty value takes precedence over the deprecated `user` parameter. If omitted, null, or empty, the API uses `user` when available. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).","examples":["user-1234"]},"user":{"type":"string","description":"Deprecated: use `safety_identifier` instead. This parameter remains accepted for backward compatibility and is used when `safety_identifier` is omitted, null, or empty. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).","examples":["user-1234"]},"output_format":{"anyOf":[{"type":"string","enum":["png","jpeg","webp"]},{"type":"null"}],"default":"png","description":"Output image format. Supported for GPT image models.","examples":["png"]},"output_compression":{"anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}],"description":"Compression level for `jpeg` or `webp` output.","examples":[100]},"moderation":{"anyOf":[{"type":"string","enum":["low","auto"]},{"type":"null"}],"default":"auto","description":"Moderation level for GPT image models.","examples":["auto"]},"background":{"anyOf":[{"type":"string","enum":["transparent","opaque","auto"]},{"type":"null"}],"default":"auto","description":"Set the background of the generated image output. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, support `opaque` and `transparent` backgrounds. Transparent backgrounds are available for supported GPT Image models. For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`.","examples":["transparent"]},"stream":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Stream partial image results as events.","examples":[false],"enum":[false,null]},"partial_images":{"$ref":"#/definitions/PartialImages"}},"required":["images","prompt"]},"ImageRefParam":{"type":"object","description":"Reference an input image by either URL or uploaded file ID.\nProvide exactly one of `image_url` or `file_id`.\n","properties":{"image_url":{"type":"string","format":"uri","maxLength":20971520,"description":"A fully qualified URL or base64-encoded data URL.","examples":["https://example.com/source-image.png"]},"file_id":{"type":"string","description":"The File API ID of an uploaded image to use as input.","examples":["file-abc123"]}},"anyOf":[{"required":["image_url"]},{"required":["file_id"]}],"not":{"required":["image_url","file_id"]},"additionalProperties":false},"PartialImages":{"anyOf":[{"type":"integer","maximum":3,"minimum":0,"default":0,"description":"The number of partial images to generate. This parameter is used for\nstreaming responses that return partial images. Value must be between 0 and 3.\nWhen set to 0, the response will be a single image sent in one streaming event.\n\nNote that the final image may be sent before the full number of partial images\nare generated if the full image is generated more quickly.\n","examples":[1]},{"type":"null"}]}}},"name":"Create image edit","id":"openai.createimageedit","example":{"body":{"images":[{"image_url":"https://example.com/source-image.png"}],"prompt":"Add a watercolor effect and keep the subject centered"}},"maxRequests":1,"summary":false}}