# Beatra Skill + MCP — Transform images with references

> Use ordered images to guide a new composition.
> Self-contained workflow guide for AI agents.
> Human-readable page: https://docs.beatra.ai/en/docs/capabilities/images/image-to-image

- 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.transform`
- Dynamic model facts: call `beatra.models.list` with `capability: "image_to_image"` 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.transform` when references guide identity, style, layout, or
content but the whole composition may change.

1. Upload local inputs with `beatra.assets.upload` and reuse their artifact IDs.
2. Keep one to four ordered input images. A source-shaped preset follows the
   last image.
3. Use `model: "auto"` unless the user requests a model. Call
   `beatra.models.list` with `capability: "image_to_image"` before choosing a
   model, control, canvas, or price.
4. Submit once with one `client_request_id`; poll with `beatra.tasks.get`.

## Tool arguments

```json
{
  "prompt": "Keep the character recognizable and place them in a winter market",
  "images": [
    { "type": "artifact", "artifact_id": "artifact_character" },
    { "type": "artifact", "artifact_id": "artifact_style" }
  ],
  "count": 1,
  "canvas": { "type": "preset", "tier": "2K", "aspect": "16:9" },
  "output_relationship": "independent",
  "client_request_id": "img-transform-opaque-1"
}
```

HTTPS URLs, artifact IDs, and small inline data URIs are accepted according to
the selected interface card. Artifact IDs are preferred for uploaded local
files and repeat use.

## Limits, defaults, and model compatibility

- Transform accepts one to four ordered input images and requests one to four
  outputs. Its default is one output on a 2K 16:9 canvas.
- `aspect: "source"` follows the last input. A target canvas requests explicit
  width and height; inspect the final artifact for actual dimensions.
- `output_relationship` defaults to `independent`; compatible models may create
  a coherent `sequence`.
- Negative prompt, prompt enhancement, palette, seed, and sequence support come
  from `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 for the complete request.
No input is dropped, merged, or reordered. The stable aliases are
`wan2.7-image-pro`, `wan2.7-image`, `qwen-image-2.0-pro`, and
`qwen-image-2.0`.

Discovery (`beatra.models.list`) is the current source of unit price and the
`successful_image_count` billing basis; do not copy prices into an agent
prompt. Tasks are charged only for successfully persisted images.

## Task status and recovery

Keep polling the same `task_id` while it is queued or running. Recover a lost
create response by sending identical arguments with the same
`client_request_id`. A changed reference, order, prompt, model, or control is a
new logical request and needs a new ID.

## REST API

Custom integrations use `POST /v1/images/image-to-image`. Follow the generated
[API operation](https://docs.beatra.ai/en/docs/api-reference/operations/images/images_i2i_v1_images_image_to_image_post)
for the complete schema. 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`.