POST
https://octopusx.ai
/
v1
/
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
}
'
{
  "created": 1735689600,
  "data": [
    {
      "url": "https://.../images/edit-abc123.png",
      "revised_prompt": "Change the background to a tech-style office while preserving the main composition"
    }
  ]
}

​
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

MethodPath
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"

​
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"
    }
  ]
}

​
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.
​
n
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.