OpenAI image edit

curl --request POST \
  --url https://api.example.com/v1/images/edits \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "images": [
    {
      "image_url": "<string>",
      "file_id": "<string>"
    }
  ],
  "prompt": "<string>",
  "model": "<string>",
  "background": "<string>",
  "input_fidelity": "<string>",
  "mask": {
    "image_url": "<string>",
    "file_id": "<string>"
  },
  "n": 123,
  "output_compression": 123,
  "output_format": "<string>",
  "partial_images": 123,
  "response_format": "<string>",
  "quality": "<string>",
  "size": "<string>",
  "stream": true,
  "user": "<string>"
}
'

import requests

url = "https://api.example.com/v1/images/edits"

payload = {
    "images": [
        {
            "image_url": "<string>",
            "file_id": "<string>"
        }
    ],
    "prompt": "<string>",
    "model": "<string>",
    "background": "<string>",
    "input_fidelity": "<string>",
    "mask": {
        "image_url": "<string>",
        "file_id": "<string>"
    },
    "n": 123,
    "output_compression": 123,
    "output_format": "<string>",
    "partial_images": 123,
    "response_format": "<string>",
    "quality": "<string>",
    "size": "<string>",
    "stream": True,
    "user": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    images: [{image_url: '<string>', file_id: '<string>'}],
    prompt: '<string>',
    model: '<string>',
    background: '<string>',
    input_fidelity: '<string>',
    mask: {image_url: '<string>', file_id: '<string>'},
    n: 123,
    output_compression: 123,
    output_format: '<string>',
    partial_images: 123,
    response_format: '<string>',
    quality: '<string>',
    size: '<string>',
    stream: true,
    user: '<string>'
  })
};

fetch('https://api.example.com/v1/images/edits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/images/edits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'images' => [
        [
                'image_url' => '<string>',
                'file_id' => '<string>'
        ]
    ],
    'prompt' => '<string>',
    'model' => '<string>',
    'background' => '<string>',
    'input_fidelity' => '<string>',
    'mask' => [
        'image_url' => '<string>',
        'file_id' => '<string>'
    ],
    'n' => 123,
    'output_compression' => 123,
    'output_format' => '<string>',
    'partial_images' => 123,
    'response_format' => '<string>',
    'quality' => '<string>',
    'size' => '<string>',
    'stream' => true,
    'user' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/images/edits"

	payload := strings.NewReader("{\n  \"images\": [\n    {\n      \"image_url\": \"<string>\",\n      \"file_id\": \"<string>\"\n    }\n  ],\n  \"prompt\": \"<string>\",\n  \"model\": \"<string>\",\n  \"background\": \"<string>\",\n  \"input_fidelity\": \"<string>\",\n  \"mask\": {\n    \"image_url\": \"<string>\",\n    \"file_id\": \"<string>\"\n  },\n  \"n\": 123,\n  \"output_compression\": 123,\n  \"output_format\": \"<string>\",\n  \"partial_images\": 123,\n  \"response_format\": \"<string>\",\n  \"quality\": \"<string>\",\n  \"size\": \"<string>\",\n  \"stream\": true,\n  \"user\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/images/edits")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"images\": [\n    {\n      \"image_url\": \"<string>\",\n      \"file_id\": \"<string>\"\n    }\n  ],\n  \"prompt\": \"<string>\",\n  \"model\": \"<string>\",\n  \"background\": \"<string>\",\n  \"input_fidelity\": \"<string>\",\n  \"mask\": {\n    \"image_url\": \"<string>\",\n    \"file_id\": \"<string>\"\n  },\n  \"n\": 123,\n  \"output_compression\": 123,\n  \"output_format\": \"<string>\",\n  \"partial_images\": 123,\n  \"response_format\": \"<string>\",\n  \"quality\": \"<string>\",\n  \"size\": \"<string>\",\n  \"stream\": true,\n  \"user\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/images/edits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"images\": [\n    {\n      \"image_url\": \"<string>\",\n      \"file_id\": \"<string>\"\n    }\n  ],\n  \"prompt\": \"<string>\",\n  \"model\": \"<string>\",\n  \"background\": \"<string>\",\n  \"input_fidelity\": \"<string>\",\n  \"mask\": {\n    \"image_url\": \"<string>\",\n    \"file_id\": \"<string>\"\n  },\n  \"n\": 123,\n  \"output_compression\": 123,\n  \"output_format\": \"<string>\",\n  \"partial_images\": 123,\n  \"response_format\": \"<string>\",\n  \"quality\": \"<string>\",\n  \"size\": \"<string>\",\n  \"stream\": true,\n  \"user\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "created": 123,
  "output_format": "<string>",
  "background": "<string>",
  "quality": "<string>",
  "size": "<string>",
  "data": [
    {
      "b64_json": "<string>",
      "revised_prompt": "<string>",
      "url": "<string>"
    }
  ],
  "usage": {
    "output_tokens_details": {
      "image_tokens": 123,
      "text_tokens": 123
    },
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123,
    "input_tokens_details": {
      "image_tokens": 123,
      "text_tokens": 123
    }
  }
}

POST

images

edits

OpenAI image edit

curl --request POST \
  --url https://api.example.com/v1/images/edits \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "images": [
    {
      "image_url": "<string>",
      "file_id": "<string>"
    }
  ],
  "prompt": "<string>",
  "model": "<string>",
  "background": "<string>",
  "input_fidelity": "<string>",
  "mask": {
    "image_url": "<string>",
    "file_id": "<string>"
  },
  "n": 123,
  "output_compression": 123,
  "output_format": "<string>",
  "partial_images": 123,
  "response_format": "<string>",
  "quality": "<string>",
  "size": "<string>",
  "stream": true,
  "user": "<string>"
}
'

import requests

url = "https://api.example.com/v1/images/edits"

payload = {
    "images": [
        {
            "image_url": "<string>",
            "file_id": "<string>"
        }
    ],
    "prompt": "<string>",
    "model": "<string>",
    "background": "<string>",
    "input_fidelity": "<string>",
    "mask": {
        "image_url": "<string>",
        "file_id": "<string>"
    },
    "n": 123,
    "output_compression": 123,
    "output_format": "<string>",
    "partial_images": 123,
    "response_format": "<string>",
    "quality": "<string>",
    "size": "<string>",
    "stream": True,
    "user": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    images: [{image_url: '<string>', file_id: '<string>'}],
    prompt: '<string>',
    model: '<string>',
    background: '<string>',
    input_fidelity: '<string>',
    mask: {image_url: '<string>', file_id: '<string>'},
    n: 123,
    output_compression: 123,
    output_format: '<string>',
    partial_images: 123,
    response_format: '<string>',
    quality: '<string>',
    size: '<string>',
    stream: true,
    user: '<string>'
  })
};

fetch('https://api.example.com/v1/images/edits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/images/edits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'images' => [
        [
                'image_url' => '<string>',
                'file_id' => '<string>'
        ]
    ],
    'prompt' => '<string>',
    'model' => '<string>',
    'background' => '<string>',
    'input_fidelity' => '<string>',
    'mask' => [
        'image_url' => '<string>',
        'file_id' => '<string>'
    ],
    'n' => 123,
    'output_compression' => 123,
    'output_format' => '<string>',
    'partial_images' => 123,
    'response_format' => '<string>',
    'quality' => '<string>',
    'size' => '<string>',
    'stream' => true,
    'user' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/images/edits"

	payload := strings.NewReader("{\n  \"images\": [\n    {\n      \"image_url\": \"<string>\",\n      \"file_id\": \"<string>\"\n    }\n  ],\n  \"prompt\": \"<string>\",\n  \"model\": \"<string>\",\n  \"background\": \"<string>\",\n  \"input_fidelity\": \"<string>\",\n  \"mask\": {\n    \"image_url\": \"<string>\",\n    \"file_id\": \"<string>\"\n  },\n  \"n\": 123,\n  \"output_compression\": 123,\n  \"output_format\": \"<string>\",\n  \"partial_images\": 123,\n  \"response_format\": \"<string>\",\n  \"quality\": \"<string>\",\n  \"size\": \"<string>\",\n  \"stream\": true,\n  \"user\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/images/edits")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"images\": [\n    {\n      \"image_url\": \"<string>\",\n      \"file_id\": \"<string>\"\n    }\n  ],\n  \"prompt\": \"<string>\",\n  \"model\": \"<string>\",\n  \"background\": \"<string>\",\n  \"input_fidelity\": \"<string>\",\n  \"mask\": {\n    \"image_url\": \"<string>\",\n    \"file_id\": \"<string>\"\n  },\n  \"n\": 123,\n  \"output_compression\": 123,\n  \"output_format\": \"<string>\",\n  \"partial_images\": 123,\n  \"response_format\": \"<string>\",\n  \"quality\": \"<string>\",\n  \"size\": \"<string>\",\n  \"stream\": true,\n  \"user\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/images/edits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"images\": [\n    {\n      \"image_url\": \"<string>\",\n      \"file_id\": \"<string>\"\n    }\n  ],\n  \"prompt\": \"<string>\",\n  \"model\": \"<string>\",\n  \"background\": \"<string>\",\n  \"input_fidelity\": \"<string>\",\n  \"mask\": {\n    \"image_url\": \"<string>\",\n    \"file_id\": \"<string>\"\n  },\n  \"n\": 123,\n  \"output_compression\": 123,\n  \"output_format\": \"<string>\",\n  \"partial_images\": 123,\n  \"response_format\": \"<string>\",\n  \"quality\": \"<string>\",\n  \"size\": \"<string>\",\n  \"stream\": true,\n  \"user\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "created": 123,
  "output_format": "<string>",
  "background": "<string>",
  "quality": "<string>",
  "size": "<string>",
  "data": [
    {
      "b64_json": "<string>",
      "revised_prompt": "<string>",
      "url": "<string>"
    }
  ],
  "usage": {
    "output_tokens_details": {
      "image_tokens": 123,
      "text_tokens": 123
    },
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123,
    "input_tokens_details": {
      "image_tokens": 123,
      "text_tokens": 123
    }
  }
}

This endpoint is compatible with the OpenAI Images protocol and generates a new image from the source images you provide and an edit prompt. It supports inpainting, outpainting, and multi-image fusion scenarios.

Features

References source images through URL addresses or file IDs
Supports inpainting with the mask image to specify the edit area
Supports outpainting with the background image for canvas extension
Supports input_fidelity to control input image fidelity (high / low)
Supports png, jpeg, and webp output formats with output_compression control
Supports both url and b64_json response formats
Supports streaming (SSE) responses with intermediate results pushed via partial_images

Authentication

Include the Authorization header in the format Bearer YOUR_API_KEY.

Supported image models

Available image models in the Model Square, please refer to Model List.

Quick example

import requests

url = "https://api.haitoken.ai/v1/images/edits"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "gpt-image-2",
    "images": [
        {"image_url": "https://example.com/images/cat.png"}
    ],
    "prompt": "Replace the background with a beach at sunset, keeping the cat unchanged",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

const response = await fetch('https://api.haitoken.ai/v1/images/edits', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    images: [
      { image_url: 'https://example.com/images/cat.png' }
    ],
    prompt: 'Replace the background with a beach at sunset, keeping the cat unchanged',
    size: '1024x1024',
    quality: 'high',
    n: 1
  })
});

const data = await response.json();
console.log(data);

curl -X POST 'https://api.haitoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/images/cat.png"}
    ],
    "prompt": "Replace the background with a beach at sunset, keeping the cat unchanged",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

A successful edit returns the image data:

{
  "created": 1787875200,
  "data": [
    {
      "url": "https://example.com/images/edited-1.png"
    }
  ],
  "size": "1024x1024",
  "quality": "high",
  "usage": {
    "input_tokens": 3280,
    "output_tokens": 4160,
    "total_tokens": 7440,
    "input_tokens_details": {
      "image_tokens": 3268,
      "text_tokens": 12
    },
    "output_tokens_details": {
      "image_tokens": 4160,
      "text_tokens": 0
    }
  }
}

Next steps

See OpenAI image generation to generate images from a text prompt
See Seedream image generation for Seedream extension parameters
See the model list for available image models

Headers

Authorization

string

required

API Key token (Bearer sk-xxx)

Content-Type

string

Body

application/json

images

object[]

required

Source images to edit

Show child attributes

prompt

string

required

Edit prompt describing the changes to apply to the image

model

string

required

Model name, e.g. "dall-e-2"

background

string

Background image data (for outpainting and similar extension scenarios)

input_fidelity

string

Input image fidelity control: high, low

mask

object

Mask image specifying the edit area (inpainting)

Show child attributes

integer

Number of images to generate

output_compression

integer

Output compression level

output_format

string

Output image format, e.g. "png", "jpeg", "webp"

partial_images

integer

Number of intermediate result images pushed per update in streaming responses

response_format

string

Response format, "url" or "b64_json"

quality

string

Image quality, e.g. "standard", "hd"

size

string

Image size, e.g. "1024x1024"

stream

boolean

Whether to use streaming (SSE) responses

user

string

End-user identifier for monitoring and abuse detection

Response

200 - application/json

created

integer<int64>

Image generation timestamp (Unix seconds)

output_format

string

Output image format echo

background

string

Background image data echo

quality

string

Image quality echo

size

string

Image size echo

data

object[]

Generated image data list

Show child attributes

usage

object

Token and image usage statistics

Show child attributes

Quick start

API documentation

AI tool integration

Other

OpenAI image edit

Features

Authentication

Supported image models

Quick example

Next steps

Headers

Body

Response

​Features

​Authentication

​Supported image models

​Quick example

​Next steps

Headers

Body

Response

Features

Authentication

Supported image models

Quick example

Next steps