OpenAI Images Compatible Image Editing

curl --request POST \
  --url https://octopusx.ai/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image": {},
  "prompt": "<string>",
  "model": "<string>",
  "mask": {},
  "n": 123,
  "size": "<string>",
  "quality": "<string>",
  "watermark": true
}
'

import requests

url = "https://octopusx.ai/v1/images/edits"

payload = {
    "image": {},
    "prompt": "<string>",
    "model": "<string>",
    "mask": {},
    "n": 123,
    "size": "<string>",
    "quality": "<string>",
    "watermark": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    image: {},
    prompt: '<string>',
    model: '<string>',
    mask: {},
    n: 123,
    size: '<string>',
    quality: '<string>',
    watermark: true
  })
};

fetch('https://octopusx.ai/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://octopusx.ai/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([
    'image' => [
        
    ],
    'prompt' => '<string>',
    'model' => '<string>',
    'mask' => [
        
    ],
    'n' => 123,
    'size' => '<string>',
    'quality' => '<string>',
    'watermark' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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://octopusx.ai/v1/images/edits"

	payload := strings.NewReader("{\n  \"image\": {},\n  \"prompt\": \"<string>\",\n  \"model\": \"<string>\",\n  \"mask\": {},\n  \"n\": 123,\n  \"size\": \"<string>\",\n  \"quality\": \"<string>\",\n  \"watermark\": true\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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://octopusx.ai/v1/images/edits")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"image\": {},\n  \"prompt\": \"<string>\",\n  \"model\": \"<string>\",\n  \"mask\": {},\n  \"n\": 123,\n  \"size\": \"<string>\",\n  \"quality\": \"<string>\",\n  \"watermark\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://octopusx.ai/v1/images/edits")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"image\": {},\n  \"prompt\": \"<string>\",\n  \"model\": \"<string>\",\n  \"mask\": {},\n  \"n\": 123,\n  \"size\": \"<string>\",\n  \"quality\": \"<string>\",\n  \"watermark\": true\n}"

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

{
  "created": 1735689600,
  "data": [
    {
      "url": "https://.../images/edit-abc123.png",
      "revised_prompt": "Change the background to a tech-style office while preserving the main composition"
    }
  ]
}

{
  "error": {
    "message": "failed to parse image edit form request",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_request"
  }
}

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "User quota is insufficient",
    "type": "new_api_error",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "The current request rate is too high, please try again later",
    "type": "new_api_error",
    "param": "",
    "code": "too_many_requests"
  }
}

{
  "error": {
    "message": "bad response body",
    "type": "new_api_error",
    "param": "",
    "code": "bad_response_body"
  }
}

POST

https://octopusx.ai

images

edits

OpenAI Images Compatible Image Editing

curl --request POST \
  --url https://octopusx.ai/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image": {},
  "prompt": "<string>",
  "model": "<string>",
  "mask": {},
  "n": 123,
  "size": "<string>",
  "quality": "<string>",
  "watermark": true
}
'

import requests

url = "https://octopusx.ai/v1/images/edits"

payload = {
    "image": {},
    "prompt": "<string>",
    "model": "<string>",
    "mask": {},
    "n": 123,
    "size": "<string>",
    "quality": "<string>",
    "watermark": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    image: {},
    prompt: '<string>',
    model: '<string>',
    mask: {},
    n: 123,
    size: '<string>',
    quality: '<string>',
    watermark: true
  })
};

fetch('https://octopusx.ai/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://octopusx.ai/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([
    'image' => [
        
    ],
    'prompt' => '<string>',
    'model' => '<string>',
    'mask' => [
        
    ],
    'n' => 123,
    'size' => '<string>',
    'quality' => '<string>',
    'watermark' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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://octopusx.ai/v1/images/edits"

	payload := strings.NewReader("{\n  \"image\": {},\n  \"prompt\": \"<string>\",\n  \"model\": \"<string>\",\n  \"mask\": {},\n  \"n\": 123,\n  \"size\": \"<string>\",\n  \"quality\": \"<string>\",\n  \"watermark\": true\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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://octopusx.ai/v1/images/edits")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"image\": {},\n  \"prompt\": \"<string>\",\n  \"model\": \"<string>\",\n  \"mask\": {},\n  \"n\": 123,\n  \"size\": \"<string>\",\n  \"quality\": \"<string>\",\n  \"watermark\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://octopusx.ai/v1/images/edits")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"image\": {},\n  \"prompt\": \"<string>\",\n  \"model\": \"<string>\",\n  \"mask\": {},\n  \"n\": 123,\n  \"size\": \"<string>\",\n  \"quality\": \"<string>\",\n  \"watermark\": true\n}"

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

{
  "created": 1735689600,
  "data": [
    {
      "url": "https://.../images/edit-abc123.png",
      "revised_prompt": "Change the background to a tech-style office while preserving the main composition"
    }
  ]
}

{
  "error": {
    "message": "failed to parse image edit form request",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_request"
  }
}

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "User quota is insufficient",
    "type": "new_api_error",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "The current request rate is too high, please try again later",
    "type": "new_api_error",
    "param": "",
    "code": "too_many_requests"
  }
}

{
  "error": {
    "message": "bad response body",
    "type": "new_api_error",
    "param": "",
    "code": "bad_response_body"
  }
}

OpenAI Images Compatible Image Editing

Image editing uses the same model family as generation, but the entry point is switched to the edit route.

Compatible with both POST /v1/images/edits and POST /v1/edits.
Supports both multipart/form-data and JSON request bodies.
Passing image enables image-to-image generation; additionally passing mask enables inpainting.
gpt-image-1 defaults to quality = standard in editing scenarios, and when n is omitted or set to 0, it falls back to 1.

Method and Path

Method	Path
`POST`	`/v1/images/edits`
`POST`	`/v1/edits`

Request Examples

curl -X POST https://octopusx.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-1" \
  -F "prompt=Change the background to a tech-style office while preserving the main composition" \
  -F "image=@input.png" \
  -F "size=1024x1024" \
  -F "watermark=false"

import requests

with open("input.png", "rb") as f:
    resp = requests.post(
        "https://octopusx.ai/v1/images/edits",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        data={
            "model": "gpt-image-1",
            "prompt": "Change the background to a tech-style office while preserving the main composition",
            "size": "1024x1024",
            "watermark": "false",
        },
        files={"image": ("input.png", f, "image/png")},
        timeout=60,
    )

print(resp.json())

const formData = new FormData();
formData.append("model", "gpt-image-1");
formData.append("prompt", "Change the background to a tech-style office while preserving the main composition");
formData.append("size", "1024x1024");
formData.append("watermark", "false");
formData.append("image", fileInput.files[0]);

const response = await fetch("https://octopusx.ai/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
  body: formData,
});

console.log(await response.json());

Response Examples

{
  "created": 1735689600,
  "data": [
    {
      "url": "https://.../images/edit-abc123.png",
      "revised_prompt": "Change the background to a tech-style office while preserving the main composition"
    }
  ]
}

{
  "error": {
    "message": "failed to parse image edit form request",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_request"
  }
}

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "User quota is insufficient",
    "type": "new_api_error",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

{
  "error": {
    "message": "The current request rate is too high, please try again later",
    "type": "new_api_error",
    "param": "",
    "code": "too_many_requests"
  }
}

{
  "error": {
    "message": "bad response body",
    "type": "new_api_error",
    "param": "",
    "code": "bad_response_body"
  }
}

Authentication

Authorization: Bearer YOUR_API_KEY

Body

image

file | string | object

required

The input image for editing. Under multipart/form-data, this is usually a file; in JSON scenarios, it can be a URL, Base64, or an object structure.

prompt

string

required

Editing instructions. Used to describe what to keep and what to modify.

model

string

Model name. If not provided, whether there is a default behavior depends on the upstream service; omitting it is not recommended.

mask

file | string | object

Inpainting mask. Transparent areas usually indicate the regions that may be edited.

integer

Number of outputs. When omitted or explicitly set to 0, the unified layer falls back to 1.

size

string

Output size. The available values depend on the target model.

quality

string

Quality field. For gpt-image-1, the editing form defaults to standard.

watermark

boolean

Explicit watermark switch. Explicitly passing false means it is turned off; omitting it means the default policy is used.

Response

created

integer

Timestamp of when the edited result was generated.

data[].url

string

URL of the resulting image.

data[].b64_json

string

Image data returned when the request uses Base64 format.

data[].revised_prompt

string

The editing prompt possibly rewritten by the upstream service.

Use Cases

Basic Image-to-Image

curl -X POST https://octopusx.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-1" \
  -F "prompt=Change the character's outfit to a dark blue suit" \
  -F "image=@portrait.png"

Inpainting

curl -X POST https://octopusx.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-1" \
  -F "prompt=Change the background to a modern office" \
  -F "image=@input.png" \
  -F "mask=@mask.png"

Using the Legacy Alias

curl -X POST https://octopusx.ai/v1/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-1" \
  -F "prompt=Preserve the main subject and enhance the lighting layers" \
  -F "image=@input.png"

Notes

Although the editing interface supports both JSON and form submissions, different upstream services have very different requirements for field shapes. The safest approach is still to submit editing fields such as image, prompt, and mask using multipart/form-data.

OpenAI Images Compatible Image Generation Video Series Overview

Overview

Text Models

Image Models

Video Models

Uploads

Tasks

Account

OpenAI Images Compatible Image Editing

OpenAI Images Compatible Image Editing

Method and Path

Request Examples

Response Examples

Authentication

Body

Response

Use Cases

Basic Image-to-Image

Inpainting

Using the Legacy Alias

Notes

​OpenAI Images Compatible Image Editing

​Method and Path

​Request Examples

​Response Examples

​Authentication

​Body

​Response

​Use Cases

​Basic Image-to-Image

​Inpainting

​Using the Legacy Alias

​Notes

​Related APIs

OpenAI Images Compatible Image Editing

Method and Path

Request Examples

Response Examples

Authentication

Body

Response

Use Cases

Basic Image-to-Image

Inpainting

Using the Legacy Alias

Notes

Related APIs