Edit Image

Use this endpoint to create an edited or extended image from one or more source images and a text prompt. This endpoint supports GPT Image models.

Endpoint

POST /v1/images/edits

Authentication

Method	Description
Bearer Token	Include Authorization: Bearer <API_key> in the request header to authenticate your account.

Headers

Parameter	Type	Required	Description
Content-Type	string	Yes	Media type of the request body. Use application/json for JSON requests or multipart/form-data for form-based image uploads
Authorization	string	Yes	Bearer API_key used to authenticate your account

Request Body

Parameter	Type	Required	Default	Description
images	array<object>	Yes	-	Input image references to edit. Minimum 1, maximum 16 images. See details below
prompt	string	Yes	-	A text description of the desired image edit, 1–32000 characters
background	string	No	auto	Background of the generated image: transparent / opaque / auto. Per-model support described below
input_fidelity	string	No	low	Fidelity to the input images: high / low. Per-model support described below
markup	object	No	-	A transparent PNG overlaid on the first input image. Supports GPT Image 2.5 models only; cannot be combined with mask. See details below
mask	object	No	-	Mask image reference. Provide exactly one of image_url or file_id; cannot be combined with markup. See details below
model	string	No	gp-im-2.5-su	The GPT image model to use for image editing. See enum values below
moderation	string	No	auto	Moderation level: low / auto
n	number	No	1	The number of edited images to generate, 1–10
output_compression	number	No	-	Compression level for jpeg or webp output, 0–100
output_format	string	No	png	Output image format: png / jpeg / webp
partial_images	number	No	0	Number of partial images for streaming responses, 0–3. When set to 0, the response is a single image sent in one streaming event. The final image may arrive before all partial images if it is generated more quickly
quality	string	No	auto	Output quality: low / medium / high / xhigh / max / auto. Per-model support described below
safety_identifier	string	No	-	A stable identifier for an end user in your organization, used for safety monitoring and abuse detection. Max length 128 characters. A non-empty value takes precedence over the deprecated user parameter
size	string	No	auto	Output image size. Standard sizes and arbitrary resolutions supported; see below
stream	boolean	No	false	Whether to stream partial image results as events
user	string	No	-	Deprecated: use safety_identifier instead. Still accepted for backward compatibility; used when safety_identifier is omitted, null, or empty

images parameters

Parameter	Type	Required	Default	Description
file_id	string	No	-	The File API ID of an uploaded image to use as input. Provide exactly one of file_id or image_url
image_url	string	No	-	A fully qualified URL or base64-encoded data URL. Max length 20971520

markup parameters

A transparent PNG overlaid on the first input image. Must match that image's dimensions after orientation and contain transparent pixels.

Parameter	Type	Required	Default	Description
file_id	string	No	-	The File API ID of an uploaded image. Provide exactly one of file_id or image_url
image_url	string	No	-	An HTTPS URL or base64-encoded data URL. Max length 20971520

mask parameters

Parameter	Type	Required	Default	Description
file_id	string	No	-	The File API ID of an uploaded mask image. Provide exactly one of file_id or image_url
image_url	string	No	-	A fully qualified URL or base64-encoded data URL. Max length 20971520

model enum values

• gp-im-1.5
• gp-im-2
• gp-im-2-2026-04-21
• gp-im-2.5-su
• gp-im-2.5-su-2026-09-08
• gp-im-2.5-fl
• gp-im-2.5-fl-2026-09-08
• gp-im-1
• gp-im-1-mini

gp-im-1 was shut down on October 23, 2026. Use gp-im-2.5-su or gp-im-2.5-fl instead.

Additional parameter notes

• background: gp-im-2.5-su and gp-im-2.5-fl, including their 2026-09-08 snapshots, support opaque and transparent backgrounds. Transparent backgrounds are available for supported GPT Image models; for gp-im-2 and gp-im-2-2026-04-21, this support is in preview. When using transparent, set the output format to png or webp.
• input_fidelity: controls how much effort the model exerts to match the style and features, especially facial features, of input images. Supports high and low on gp-im-1.5; gp-im-1-mini supports only low; for gp-im-2, omit this parameter. Defaults to low on supported models.
• quality: GPT Image models support low, medium, and high; gp-im-2.5-su and gp-im-2.5-fl, including their 2026-09-08 snapshots, also support xhigh and max.
• size: for gp-im-2, gp-im-2-2026-04-21, gp-im-2.5-su, gp-im-2.5-su-2026-09-08, gp-im-2.5-fl, and gp-im-2.5-fl-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.
• safety_identifier: hash a username or email address to avoid sending identifying information. If omitted, null, or empty, the API uses user when available.

Request Examples

Edit image

curl --request POST 'https://neolink.com/api/v1/images/edits' \
     --header 'Authorization: Bearer <API Key>' \
     --form 'model=gp-im-1.5' \
     --form 'image[]=@body-lotion.png' \
     --form 'image[]=@bath-bomb.png' \
     --form 'image[]=@incense-kit.png' \
     --form 'image[]=@soap.png' \
     --form 'prompt=Create a lovely gift basket with these four items in it'

Streaming edit

curl --request POST 'https://neolink.com/api/v1/images/edits' \
     --header 'Authorization: Bearer <API Key>' \
     --form 'model=gp-im-1.5' \
     --form 'image[]=@body-lotion.png' \
     --form 'image[]=@bath-bomb.png' \
     --form 'image[]=@incense-kit.png' \
     --form 'image[]=@soap.png' \
     --form 'prompt=Create a lovely gift basket with these four items in it' \
     --form 'stream=true' \
     --no-buffer

Image URL

curl --request POST 'https://neolink.com/api/v1/images/edits' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "images": [
             {
                 "image_url": "https://example.com/source-image.png"
             }
         ],
         "prompt": "Add a watercolor effect to this image",
         "model": "gp-im-1.5",
         "quality": "high",
         "size": "1024x1024"
     }'

File ID

curl --request POST 'https://neolink.com/api/v1/images/edits' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "images": [
             {
                 "file_id": "file-abc123"
             }
         ],
         "prompt": "Replace the background with a snowy mountain scene",
         "mask": {
             "file_id": "file-mask123"
         },
         "model": "gp-im-1.5",
         "output_compression": 100,
         "output_format": "png"
     }'

Response Body

Parameter	Type	Description
created	number	The Unix timestamp (in seconds) of when the image was created
background	string	The background parameter used for the image generation: transparent or opaque
data	array<object>	The list of generated images. See details below
output_format	string	The output format of the image generation: png / webp / jpeg
quality	string	The quality of the image generated: low / medium / high / xhigh / max
safety_identifier	string	The effective safety identifier used for safety monitoring and abuse detection. This is the non-empty safety_identifier from the request, or the deprecated user value when safety_identifier is omitted, null, or empty
size	string	The image dimensions as a WIDTHxHEIGHT string, for example 1536x864
usage	object	For gp-im-1 only, the token usage information for the image generation. See details below

data parameters

Parameter	Type	Description
b64_json	string	The base64-encoded JSON of the generated image. Returned by default for GPT Image models, or when response_format is set to b64_json for models that support that parameter
revised_prompt	string	The revised prompt used to generate the image, for models that support prompt revision. Not returned by GPT Image models
url	string	The URL of the generated image when response_format is set to url for models that support that parameter. Unsupported for GPT Image models

usage parameters

Parameter	Type	Description
input_tokens	number	The number of tokens (images and text) in the input prompt
input_tokens_details.image_tokens	number	The number of image tokens in the input prompt
input_tokens_details.text_tokens	number	The number of text tokens in the input prompt
output_tokens	number	The number of output tokens generated by the model
output_tokens_details.image_tokens	number	The number of image output tokens generated by the model
output_tokens_details.text_tokens	number	The number of text output tokens generated by the model
total_tokens	number	The total number of tokens (images and text) used for the image generation

Response Example

Non-streaming response:

{
  "created": 0,
  "background": "transparent",
  "data": [
    {
      "b64_json": "b64_json",
      "revised_prompt": "revised_prompt",
      "url": "https://example.com"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "safety_identifier": "safety_identifier",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    },
    "output_tokens": 0,
    "total_tokens": 0,
    "output_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    }
  }
}

Streaming response: when stream is true, the response is returned as an SSE event stream. Partial images are delivered via image_edit.partial_image events (partial_image_index indicates the partial image index), and the final result is returned via the image_edit.completed event:

event: image_edit.partial_image
data: {"type":"image_edit.partial_image","b64_json":"...","partial_image_index":0}

event: image_edit.completed
data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":100,"input_tokens":50,"output_tokens":50,"input_tokens_details":{"text_tokens":10,"image_tokens":40}}}