# Edit a base image
> Preserve a base image while applying an instruction or bounded change.

Preserve a base image while applying an instruction or bounded change.

## Primary agent path

Use `beatra.images.edit` when the first image must remain the base canvas. Later
ordered images may guide the edit.

1. Upload local inputs with `beatra.assets.upload` and use the returned artifact
   IDs.
2. Put the base first, followed by up to three optional references.
3. Call `beatra.models.list` with `capability: "image_edit"` when model,
   region, control, canvas, or price compatibility matters. Otherwise use
   `model: "auto"`.
4. Submit once with one `client_request_id`; poll with `beatra.tasks.get`.

## AI guide

AI integration guide: https://docs.beatra.ai/llms/images-edit.md

## Tool arguments

```json
{
  "prompt": "Replace the sign inside the selected area and preserve everything else",
  "images": [
    { "type": "artifact", "artifact_id": "artifact_base" }
  ],
  "edit_regions": [
    { "image_index": 0, "x": 0.58, "y": 0.20, "width": 0.30, "height": 0.18 }
  ],
  "count": 1,
  "canvas": { "type": "preset", "tier": "2K", "aspect": "source" },
  "client_request_id": "img-edit-opaque-1"
}
```

Each normalized region must remain inside its image. Each input can have at
most two regions. Omit `edit_regions` for a whole-image instruction.

## Limits, defaults, and model compatibility

- Edit accepts one to four ordered input images and requests one to four
  outputs. The first image is the base.
- Edit defaults to a 2K canvas whose ratio follows the first image; `count`
  defaults to 1.
- Exact canvas, negative prompt, prompt enhancement, palette, region, and seed
  support is described by `beatra.models.list`.
- Explicit Qwen Image 2.0 and 3.0 requests accept at most three inputs. `auto` keeps the
  public maximum of four by selecting an eligible model. Incompatible explicit
  requests fail before charge and never discard an input.

The stable aliases are `qwen-image-3.0-pro`, `qwen-image-3.0`,
`wan2.7-image-pro`, `wan2.7-image`, `qwen-image-2.0-pro`, and
`qwen-image-2.0`. Qwen Image 3 is initially named-only and does not change
`auto`. Read `pricing.options` from live discovery and select the option
matching the actual output resolution. Billing settles to the number of
successfully persisted images, including partial output; input references do
not add extra credits for each reference image. Do not copy models or prices into an agent
prompt.

## Task status and recovery

Poll the same `task_id` until terminal. Retry a lost create response only with
identical arguments and the same `client_request_id`. Any new instruction,
input order, region, model, or output setting is new work and needs a new ID.

## REST API

Custom integrations use `POST /v1/images/edits`. Follow the generated
[API operation](https://docs.beatra.ai/en/docs/api-reference/operations/images/images_edits_v1_images_edits_post)
for the complete contract. Skill + MCP is the recommended integration; REST serves custom applications.