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

# Image editing

> Edit an image with model-supported reference inputs, masks, and output settings.

Use `POST https://api.apione.ai/v1/images/edits` to edit images.

## Before running examples

Install Python 3, then install the dependency with the same interpreter that will run the example:

```bash theme={null}
python -m pip install requests
```

If your system uses `python3`, use `python3` for both installation and execution. Windows users can use `py -m pip install requests` and `py example.py`. Activate your virtual environment first, if applicable.

Create a key on the [API Keys page](https://apione.ai/en/app/api-keys), copy a model ID that supports image editing from the [available model list](https://apione.ai/docs/en/models/catalog.md), then set the variables in the terminal where you will run the script. The uppercase values below are placeholders to replace.

> [tab] macOS / Linux
>
> ```bash theme={null}
> export APIONE_API_KEY="YOUR_APIONE_API_KEY"
> export APIONE_IMAGE_EDIT_MODEL="YOUR_IMAGE_EDIT_MODEL"
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $env:APIONE_API_KEY = "YOUR_APIONE_API_KEY"
> $env:APIONE_IMAGE_EDIT_MODEL = "YOUR_IMAGE_EDIT_MODEL"
> ```

Variables only apply to the current terminal and child processes it starts. Run the examples in the same terminal; IDEs, containers, and new terminals need separate configuration. Do not commit real keys to source control.

## Pre-request confirmation

1. The current key can call the target image editing model.
2. `/v1/models/{model}/params` shows that the model supports editing or reference image input.
3. Image type, size, count, and delivery method meet the model's requirements.

## Request structure

The request needs at least a model, editing prompt, and image input. Different models may use image URL, Base64, file ID, or other fields, so follow the parameter query results first.

```json theme={null}
{
  "model": "YOUR_IMAGE_EDIT_MODEL",
  "prompt": "Keep the subject composition and change the background to a beach at sunset",
  "image": "MODEL_SUPPORTED_IMAGE_INPUT"
}
```

Send the request to:

```text theme={null}
POST https://api.apione.ai/v1/images/edits
Authorization: Bearer YOUR_APIONE_API_KEY
Content-Type: application/json
```

> [!NOTE]
>
> If the model requires multipart, a dedicated reference image field, or an additional mask, use the fields from that model's parameter page strictly. Do not treat the structural example above as a fixed format for all models.

## Validate results

* Whether the subject and edited area match the prompt.
* Whether image dimensions, format, and transparency channel meet business requirements.
* Request status, usage, and cost in the console.
* Whether the request ID in the response can be retrieved in the details.

## Editing task breakdown

First determine which type of edit it is, then choose a model that supports that capability:

| Task | What to confirm |
| - | - |
| Full redraw | Reference image input, prompt, strength or similarity parameter |
| Local modification | Whether mask is supported, mask format, and coordinate rules |
| Background replacement | Transparency channel, subject preservation capability, output format |
| Multi-image fusion | Reference image count, order, size, and weight |
| Style transfer | Whether a style field exists, or is controlled only by prompt |

## Request preparation workflow

1. Find available image editing models through `/v1/models`.
2. Query `/v1/models/{model}/params` to confirm the image input method.
3. Check file format, pixel dimensions, and file size locally.
4. Start with one small image and a simple prompt for validation.
5. Print the full response and request ID before implementing result download.

If the parameter page requires JSON URL or Base64, construct JSON according to the model declaration; if it requires `multipart/form-data`, use file upload fields instead of forcing JSON.

## Python request template

The template below is only for cases where the target model explicitly supports a JSON `image` field. Set `APIONE_IMAGE_INPUT` to a picture URL, Base64, or file ID accepted by that field. If using a URL, it must be readable by the server; a local path (such as `C:\images\input.png`) cannot be used directly as a remote image URL. If the model uses other fields or multipart, adjust the request according to the parameter documentation.

```bash macOS / Linux theme={null}
export APIONE_IMAGE_INPUT="MODEL_SUPPORTED_IMAGE_INPUT"
```

```powershell Windows PowerShell theme={null}
$env:APIONE_IMAGE_INPUT = "MODEL_SUPPORTED_IMAGE_INPUT"
```

```python theme={null}
import os
import requests

payload = {
    "model": os.environ["APIONE_IMAGE_EDIT_MODEL"],
    "prompt": "Keep the subject composition and change the background to a beach at sunset",
    "image": os.environ["APIONE_IMAGE_INPUT"],
}

response = requests.post(
    "https://api.apione.ai/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['APIONE_API_KEY']}"},
    json=payload,
    timeout=180,
)
print(response.status_code, {name: response.headers[name] for name in ("X-Request-ID", "X-Maxx-Trace-Id", "X-Maxx-Request-ID") if name in response.headers})
print(response.text)
response.raise_for_status()
```

## Result quality checks

* Whether subject identity, text, logo, or product structure was unexpectedly changed.
* Whether mask edges show obvious seams.
* Whether output dimensions and transparency channel are preserved.
* Whether reference images contain unauthorized personal or commercial material.
* Whether retries generated multiple results and incurred duplicate charges.

## Common errors

| Symptom | Check first |
| - | - |
| 400 parameter error | Field names, input type, Base64 prefix, URL accessibility |
| 413 request too large | Image size, count, and encoded volume |
| 415 or format error | Whether `Content-Type` matches model requirements |
| Edit effect resembles regeneration | Whether the model supports editing, and whether the prompt explicitly states what to preserve |
| Success but result cannot be downloaded | URL validity period, network, and file storage permissions |

When images contain sensitive data, do not save original images, full Base64, or authenticated download URLs in logs.

## When parameter metadata is empty

HTTP 200 with `params: []`, `request: {}`, or an empty `billingMode` means those details were not declared in this response. It does not prove that a capability is unsupported, permit arbitrary parameters, or indicate a free call. The `usage`, `request`, `second`, and `image` entries in `chargeModes` are listed mode names, not proof that a model bills all four ways.

1. Check the APIONE model details and current key group for protocols and prices.
2. Use confirmed model-specific instructions for size, quality, reference images, masks, and other fields; do not copy enums from another model.
3. Without confirmed parameter instructions, verify the minimal request first and avoid optional fields or batch jobs.
4. Contact support with the model ID, endpoint, time, and actual request identifiers. Do not send the full key.

Next: [Image generation](https://apione.ai/docs/en/api/images-generations.md), [Media parameters](https://apione.ai/docs/en/api/media-parameters.md), [Troubleshooting](https://apione.ai/docs/en/support/errors.md), [Request reliability](https://apione.ai/docs/en/api/request-reliability.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.