JSON image edits: choosing URLs, file IDs, or multipart uploads

The interface change

OpenAI added JSON request support to /v1/images/edits on February 9, 2026, accepting image_url or file_id for images and an optional mask.

Match the input to your storage flow

If your application already receives an uploaded file, multipart handling may be the simplest path. A URL-based workflow can fit assets already stored by your system, while file identifiers require their own lifecycle and access checks. Choose the path that is easiest to operate and audit.

Confirm support in the service you call. A provider feature announcement does not by itself mean every integration accepts the new request shape.

Treat source access as part of the job

For a URL input, make sure the image can be retrieved when the job executes. A link that expires while a request waits in your queue can turn an otherwise valid brief into a failed job. Avoid publicly exposing private customer material merely to simplify a fetch.

Keep masks paired with their source image and record any preprocessing. Unexpected dimensions, orientation changes, or a stale reference can make an edit difficult to diagnose.

Preserve a working fallback

Before changing an existing upload flow, test accepted formats, error reporting, and retry behavior with representative files. Retain a known working request example for the specific endpoint and model your application uses.