resources/images/methods/edit/index.md

Create image edit

post /images/edits

Create image edit

Returns

ImagesResponse object { created, background, data, 4 more }

The response from the image generation endpoint.
- created: number
  
  The Unix timestamp (in seconds) of when the image was created.
- background: optional "transparent" or "opaque"
  
  The background parameter used for the image generation. Either transparent or opaque.
  - "transparent"
  - "opaque"
- data: optional array of Image
  
  The list of generated images.
  - b64_json: optional string
    
    The base64-encoded JSON of the generated image. Returned by default for the GPT image models, and only present if response_format is set to b64_json for dall-e-2 and dall-e-3.
  - revised_prompt: optional string
    
    For dall-e-3 only, the revised prompt that was used to generate the image.
  - url: optional string
    
    When using dall-e-2 or dall-e-3, the URL of the generated image if response_format is set to url (default value). Unsupported for the GPT image models.
- output_format: optional "png" or "webp" or "jpeg"
  
  The output format of the image generation. Either png, webp, or jpeg.
  - "png"
  - "webp"
  - "jpeg"
- quality: optional "low" or "medium" or "high"
  
  The quality of the image generated. Either low, medium, or high.
  - "low"
  - "medium"
  - "high"
- size: optional "1024x1024" or "1024x1536" or "1536x1024"
  
  The size of the image generated. Either 1024x1024, 1024x1536, or 1536x1024.
  - "1024x1024"
  - "1024x1536"
  - "1536x1024"
- usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }
  
  For gpt-image-1 only, the token usage information for the image generation.
  - input_tokens: number
    
    The number of tokens (images and text) in the input prompt.
  - input_tokens_details: object { image_tokens, text_tokens }
    
    The input tokens detailed information for the image generation.
    - image_tokens: number
      
      The number of image tokens in the input prompt.
    - text_tokens: number
      
      The number of text tokens in the input prompt.
  - output_tokens: number
    
    The number of output tokens generated by the model.
  - total_tokens: number
    
    The total number of tokens (images and text) used for the image generation.
  - output_tokens_details: optional object { image_tokens, text_tokens }
    
    The output token details for the image generation.
    - image_tokens: number
      
      The number of image output tokens generated by the model.
    - text_tokens: number
      
      The number of text output tokens generated by the model.

Example

curl https://api.openai.com/v1/images/edits \
    -H 'Content-Type: multipart/form-data' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -F image='Example data' \
    -F prompt='A cute baby sea otter wearing a beret' \
    -F background=transparent \
    -F n=1 \
    -F output_compression=100 \
    -F output_format=png \
    -F partial_images=1 \
    -F quality=high \
    -F response_format=url \
    -F user=user-1234

Response

{
  "created": 0,
  "background": "transparent",
  "data": [
    {
      "b64_json": "b64_json",
      "revised_prompt": "revised_prompt",
      "url": "https://example.com"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "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
    }
  }
}

Edit image

curl -s -D >(grep -i x-request-id >&2) \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \
  -X POST "https://api.openai.com/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "model=gpt-image-1.5" \
  -F "image[]=@body-lotion.png" \
  -F "image[]=@bath-bomb.png" \
  -F "image[]=@incense-kit.png" \
  -F "image[]=@soap.png" \
  -F 'prompt=Create a lovely gift basket with these four items in it'

Streaming

curl -s -N -X POST "https://api.openai.com/v1/images/edits" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "model=gpt-image-1.5" \
  -F "image[]=@body-lotion.png" \
  -F "image[]=@bath-bomb.png" \
  -F "image[]=@incense-kit.png" \
  -F "image[]=@soap.png" \
  -F 'prompt=Create a lovely gift basket with these four items in it' \
  -F "stream=true"

Response

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}}}

resources/images/methods/edit/index.md +198 −0 created

1## Create image edit

3**post** `/images/edits`

5Create image edit

7### Returns

9- `ImagesResponse object { created, background, data, 4 more }`

11 The response from the image generation endpoint.

13 - `created: number`

15 The Unix timestamp (in seconds) of when the image was created.

17 - `background: optional "transparent" or "opaque"`

19 The background parameter used for the image generation. Either `transparent` or `opaque`.

21 - `"transparent"`

23 - `"opaque"`

25 - `data: optional array of Image`

27 The list of generated images.

29 - `b64_json: optional string`

31 The base64-encoded JSON of the generated image. Returned by default for the GPT image models, and only present if `response_format` is set to `b64_json` for `dall-e-2` and `dall-e-3`.

33 - `revised_prompt: optional string`

35 For `dall-e-3` only, the revised prompt that was used to generate the image.

37 - `url: optional string`

39 When using `dall-e-2` or `dall-e-3`, the URL of the generated image if `response_format` is set to `url` (default value). Unsupported for the GPT image models.

41 - `output_format: optional "png" or "webp" or "jpeg"`

43 The output format of the image generation. Either `png`, `webp`, or `jpeg`.

45 - `"png"`

47 - `"webp"`

49 - `"jpeg"`

51 - `quality: optional "low" or "medium" or "high"`

53 The quality of the image generated. Either `low`, `medium`, or `high`.

55 - `"low"`

57 - `"medium"`

59 - `"high"`

61 - `size: optional "1024x1024" or "1024x1536" or "1536x1024"`

63 The size of the image generated. Either `1024x1024`, `1024x1536`, or `1536x1024`.

65 - `"1024x1024"`

67 - `"1024x1536"`

69 - `"1536x1024"`

71 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`

73 For `gpt-image-1` only, the token usage information for the image generation.

75 - `input_tokens: number`

77 The number of tokens (images and text) in the input prompt.

79 - `input_tokens_details: object { image_tokens, text_tokens }`

81 The input tokens detailed information for the image generation.

83 - `image_tokens: number`

85 The number of image tokens in the input prompt.

87 - `text_tokens: number`

89 The number of text tokens in the input prompt.

91 - `output_tokens: number`

93 The number of output tokens generated by the model.

95 - `total_tokens: number`

97 The total number of tokens (images and text) used for the image generation.

99 - `output_tokens_details: optional object { image_tokens, text_tokens }`

100

101 The output token details for the image generation.

102

103 - `image_tokens: number`

104

105 The number of image output tokens generated by the model.

106

107 - `text_tokens: number`

108

109 The number of text output tokens generated by the model.

110

111### Example

112

113```http

114curl https://api.openai.com/v1/images/edits \

115 -H 'Content-Type: multipart/form-data' \

116 -H "Authorization: Bearer $OPENAI_API_KEY" \

117 -F image='Example data' \

118 -F prompt='A cute baby sea otter wearing a beret' \

119 -F background=transparent \

120 -F n=1 \

121 -F output_compression=100 \

122 -F output_format=png \

123 -F partial_images=1 \

124 -F quality=high \

125 -F response_format=url \

126 -F user=user-1234

127```

128

129#### Response

130

131```json

132{

133 "created": 0,

134 "background": "transparent",

135 "data": [

136 {

137 "b64_json": "b64_json",

138 "revised_prompt": "revised_prompt",

139 "url": "https://example.com"

140 }

141 ],

142 "output_format": "png",

143 "quality": "low",

144 "size": "1024x1024",

145 "usage": {

146 "input_tokens": 0,

147 "input_tokens_details": {

148 "image_tokens": 0,

149 "text_tokens": 0

150 },

151 "output_tokens": 0,

152 "total_tokens": 0,

153 "output_tokens_details": {

154 "image_tokens": 0,

155 "text_tokens": 0

156 }

157 }

158}

159```

160

161### Edit image

162

163```http

164curl -s -D >(grep -i x-request-id >&2) \

165 -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \

166 -X POST "https://api.openai.com/v1/images/edits" \

167 -H "Authorization: Bearer $OPENAI_API_KEY" \

168 -F "model=gpt-image-1.5" \

169 -F "image[]=@body-lotion.png" \

170 -F "image[]=@bath-bomb.png" \

171 -F "image[]=@incense-kit.png" \

172 -F "image[]=@soap.png" \

173 -F 'prompt=Create a lovely gift basket with these four items in it'

174```

175

176### Streaming

177

178```http

179curl -s -N -X POST "https://api.openai.com/v1/images/edits" \

180 -H "Authorization: Bearer $OPENAI_API_KEY" \

181 -F "model=gpt-image-1.5" \

182 -F "image[]=@body-lotion.png" \

183 -F "image[]=@bath-bomb.png" \

184 -F "image[]=@incense-kit.png" \

185 -F "image[]=@soap.png" \

186 -F 'prompt=Create a lovely gift basket with these four items in it' \

187 -F "stream=true"

188```

189

190#### Response

191

192```json

193event: image_edit.partial_image

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

195

196event: image_edit.completed

197data: {"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}}}

198```

resources/images/methods/edit/index.md 2026-07-07 08:02 UTC to 2026-07-09 20:58 UTC

Create image edit

Returns

Example

Response

Edit image

Streaming

Response