Transform images with references

Primary agent path

Use beatra.images.transform when references guide identity, style, layout, or content but the whole composition may change.

Upload local inputs with beatra.assets.upload and reuse their artifact IDs.
Keep one to four ordered input images. A source-shaped preset follows the last image.
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.
Submit once with one client_request_id; poll with beatra.tasks.get.

AI guide

MCP integration guide for AI

For custom API integrations, copy this guide into Claude, Codex, or another coding assistant.

Markdown

Tool arguments

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