Edit a base image

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

Tool arguments

{
  "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 for the complete contract. Skill + MCP is the recommended integration; REST serves custom applications.