Image editing

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:

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, copy a model ID that supports image editing from the available model list, then set the variables in the terminal where you will run the script. The uppercase values below are placeholders to replace.

macOS / Linux
Windows PowerShell

export APIONE_API_KEY="YOUR_APIONE_API_KEY"
export APIONE_IMAGE_EDIT_MODEL="YOUR_IMAGE_EDIT_MODEL"

$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

The current key can call the target image editing model.
/v1/models/{model}/params shows that the model supports editing or reference image input.
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.

{
  "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:

POST https://api.apione.ai/v1/images/edits
Authorization: Bearer YOUR_APIONE_API_KEY
Content-Type: application/json

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

Find available image editing models through /v1/models.
Query /v1/models/{model}/params to confirm the image input method.
Check file format, pixel dimensions, and file size locally.
Start with one small image and a simple prompt for validation.
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.

export APIONE_IMAGE_INPUT="MODEL_SUPPORTED_IMAGE_INPUT"

$env:APIONE_IMAGE_INPUT = "MODEL_SUPPORTED_IMAGE_INPUT"

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.

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

Next: Image generation, Media parameters, Troubleshooting, Request reliability.

Addresses and authentication

Model APIs

Output and advanced usage

Image APIs

Video APIs

Before running examples

Pre-request confirmation

Request structure

Validate results

Editing task breakdown

Request preparation workflow

Python request template

Result quality checks

Common errors

When parameter metadata is empty