> ## Documentation Index
> Fetch the complete documentation index at: https://doc.octopusx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Images Compatible Image Editing

> Use `POST /v1/images/edits` or `POST /v1/edits` to perform editing, inpainting, and image-to-image generation based on existing images.

# 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

<CodeGroup>
  ```bash theme={null}
  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"
  ```

  ```python theme={null}
  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())
  ```

  ```javascript theme={null}
  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());
  ```
</CodeGroup>

## Response Examples

<ResponseExample>
  ```json 200 theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "url": "https://.../images/edit-abc123.png",
        "revised_prompt": "Change the background to a tech-style office while preserving the main composition"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "failed to parse image edit form request",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key provided",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "User quota is insufficient",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "message": "The current request rate is too high, please try again later",
      "type": "new_api_error",
      "param": "",
      "code": "too_many_requests"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "bad response body",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response_body"
    }
  }
  ```
</ResponseExample>

## Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="image" type="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.
</ParamField>

<ParamField body="prompt" type="string" required>
  Editing instructions. Used to describe what to keep and what to modify.
</ParamField>

<ParamField body="model" type="string">
  Model name. If not provided, whether there is a default behavior depends on the upstream service; omitting it is not recommended.
</ParamField>

<ParamField body="mask" type="file | string | object">
  Inpainting mask. Transparent areas usually indicate the regions that may be edited.
</ParamField>

<ParamField body="n" type="integer">
  Number of outputs. When omitted or explicitly set to `0`, the unified layer falls back to `1`.
</ParamField>

<ParamField body="size" type="string">
  Output size. The available values depend on the target model.
</ParamField>

<ParamField body="quality" type="string">
  Quality field. For `gpt-image-1`, the editing form defaults to `standard`.
</ParamField>

<ParamField body="watermark" type="boolean">
  Explicit watermark switch. Explicitly passing `false` means it is turned off; omitting it means the default policy is used.
</ParamField>

## Response

<ResponseField name="created" type="integer">
  Timestamp of when the edited result was generated.
</ResponseField>

<ResponseField name="data[].url" type="string">
  URL of the resulting image.
</ResponseField>

<ResponseField name="data[].b64_json" type="string">
  Image data returned when the request uses Base64 format.
</ResponseField>

<ResponseField name="data[].revised_prompt" type="string">
  The editing prompt possibly rewritten by the upstream service.
</ResponseField>

## Use Cases

### Basic Image-to-Image

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

<Warning>
  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`.
</Warning>

## Related APIs

* [OpenAI Images Compatible Overview](./overview)
* [OpenAI Images Compatible Image Generation](./generation)