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 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 is admitted. 4K transform auto selects Flare.

Discovery (beatra.models.list) is the current source of pricing.options; select the option matching the admitted output resolution. Tasks are charged only for successfully persisted images. Input references do not multiply customer credits; 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 for the complete schema. Skill + MCP is the recommended integration; REST serves custom applications.