# Transform images with references
> Use ordered images to guide a new composition.

Use ordered images to guide a new composition.

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

## AI guide

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

## 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 and 3.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
`qwen-image-3.0-pro`, `qwen-image-3.0`, `wan2.7-image-pro`,
`wan2.7-image`, `qwen-image-2.0-pro`, `qwen-image-2.0`,
`gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, and `gpt-image-2`.
Qwen Image 3 is in image-to-image `auto`. GPT Image 2.5 Flare and Sunburst
sit in image-to-image `auto` immediately before GPT Image 2, still behind
Qwen and Wan. They accept up to four ordered references and exactly one
independent output on a preset `1K`, `2K`, or `4K` canvas, with a
20,000-character prompt. They do not accept a target canvas, seed, negative
prompt, prompt enhancement, reasoning, or palette. Published
per-successful-image prices are 90/150/230 credits for GPT Image 2 and
180/300/460 credits for both 2.5 models. A 4K `1:1` request can be accepted.
4K transform `auto` selects Flare.

Discovery (`beatra.models.list`) is the current source of
`pricing.options`; select the option matching the actual output resolution.
Tasks are charged only for successfully persisted images. Input references do
not add extra credits for each reference image; the hidden supplier input cost is covered by
Beatra. Do not copy models or prices into an agent prompt.

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