# Beatra Skill + MCP — Edit a base image

> Preserve a base image while applying an instruction or bounded change.
> Self-contained workflow guide for AI agents.
> Human-readable page: https://docs.beatra.ai/en/docs/capabilities/images/image-edit

- Primary surface: the Universal Beatra Skill with authenticated MCP.
- Install or reconnect: https://beatra.ai/install.md
- MCP endpoint: `https://mcp.beatra.ai/mcp`
- Billable action: `beatra.images.edit`
- Dynamic model facts: call `beatra.models.list` with `capability: "image_edit"` only when model constraints, controls, or prices matter.
- Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal.
- Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response.

REST/OpenAPI is the fallback protocol path, not the primary agent packaging.

---

## 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`.

## 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 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 `wan2.7-image-pro`, `wan2.7-image`,
`qwen-image-2.0-pro`, and `qwen-image-2.0`. Per-image prices come from live
discovery (`beatra.models.list`); do not copy them into an agent prompt.
Billing settles to the number of successfully persisted images, including
partial output.

## 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.

---

## Appendix: shared Skill + MCP contract

### Retry identity

One logical generation has one `client_request_id`. If the create response is
lost, retry the exact same arguments with that ID. If any prompt, media, model,
or output control changes, use a new ID. Never create another paid task merely
because the first task is `queued` or `running`.

### Polling and billing truth

Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`,
`failed`, or `canceled`. Only the task response is authoritative for the
resolved model, artifacts, charged credits, and refunded credits.

### Recovery

Preserve structured Beatra error codes. Reconnect on authentication failure;
stop and request a balance action on insufficient balance; refresh current
constraints with `beatra.models.list` after model validation; request a new
upload grant after expiration or MIME/length mismatch. Changed generation
arguments always require a new `client_request_id`.