---
title: "Transform one to four ordered reference images"
method: POST
path: "/v1/images/image-to-image"
tags: ["images"]
---

# Transform one to four ordered reference images

`POST /v1/images/image-to-image`

## Request

- Base URL: `https://api.beatra.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.beatra.ai/v1/images/image-to-image`
- Auth: none declared. Required headers: `Idempotency-Key`

Create an asynchronous task that uses one to four ordered images as references for a new result. `auto` selects a compatible live model; incompatible concrete-model requests are rejected without dropping references or changing controls.

## Headers

- `x-request-id` string, nullable
- `Idempotency-Key` string, required
- `authorization` string, nullable

## Request body

- ImageToImageRequest: Transform one to four ordered image references with a prompt.
  - `metadata` object, nullable: Caller-supplied metadata; ≤16 keys, key ≤64 chars, value ≤512 chars
  - `callback_url` string, nullable: HTTPS URL beatra will POST the final Task envelope to when the Task reaches a terminal state
  - `callback_signing_key_id` string, nullable: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided.
  - `model` 'auto' | 'gpt-image-2.5-flare' | 'gpt-image-2.5-sunburst' | 'gpt-image-2' | 'image-01-live' | 'wan2.7-image-pro' | 'wan2.7-image' | 'qwen-image-3.0-pro' | 'qwen-image-3.0' | 'qwen-image-2.0-pro' | 'qwen-image-2.0': Use auto for compatibility-based selection from the configured live candidates. A concrete model is evaluated exactly as requested and is never substituted.
  - `prompt` string, required: Required prompt containing at least one non-whitespace character.
  - `count` integer: Requested output image count. The public range is one through four, and the selected model must support the exact count; Beatra does not split the request.
  - `canvas` union: Desired output canvas. Preset `source` inherits the last input image's ratio; the omitted default is 2K at 16:9.
    - ImageTransformPresetCanvas: Transform canvas whose ratio may be inherited from the last input image.
      - `type` 'preset', required
      - `tier` '1K' | '2K' | '4K', required: Named quality tier, not a promise of exact encoded dimensions.
      - `aspect` string, nullable: Positive width:height ratio with integer components from 1 to 999999, or `source` to inherit the last input image's ratio. Positive ratios are normalized by greatest common divisor.
    - ImageTargetCanvas: Desired pixel target; the selected implementation may normalize actual output.
      - `type` 'target', required
      - `width` integer, required: Desired output width in pixels
      - `height` integer, required: Desired output height in pixels
  - `seed` integer, nullable: Optional random seed. Supplying it constrains model eligibility; omit it for model-managed randomness.
  - `negative_prompt` string, nullable: Optional content or qualities to avoid. Supplying it constrains model eligibility and is rejected when no compatible model is available.
  - `enhance_prompt` boolean, nullable: Ask the model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written; an explicit boolean constrains model eligibility.
  - `palette` ImagePaletteColor[], nullable: Three to ten weighted RGB colors. Runtime validation requires the weights to sum exactly to 1.0000.
    - `color` string, required
    - `weight` union, required: Exact decimal weight greater than 0 and at most 1, with no more than 4 fractional digits. Decimal strings avoid binary-float ambiguity.
      - number
      - string
  - `images` union[], required: Ordered artifact, HTTPS URL, or data URI references.
    - union
      - ImageMediaInputUrl: Closed HTTPS image reference accepted by Beatra.
        - `type` 'url', required
        - `url` string, required: Public HTTPS image URL with a non-empty host.
      - ImageMediaInputArtifact: Closed reference to a Beatra artifact.
        - `type` 'artifact', required
        - `artifact_id` string, required
      - ImageMediaInputDataUri: Closed inline image reference accepted by Beatra.
        - `type` 'data_uri', required
        - `data` string, required: Data URI with a 256 KiB encoded inline transport cap. This is not the model image-byte limit; use an artifact or public HTTPS URL for larger inputs.
  - `output_relationship` 'independent' | 'sequence'

## Response `202`

Task accepted

- TaskEnvelope: Standard Task envelope. Returned by every async-creation endpoint, GET /v1/tasks/{id}, and the body of customer callback POSTs.
  - `object` 'task'
  - `task_id` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
  - `capability` string, required
  - `workload_type` 'model' | 'social_operation'
  - `model` string, nullable: Caller-requested model verbatim (may be 'auto'). Null for social_operation tasks.
  - `resolved_model` string, nullable: Actual model that ran (null until execution starts; equals model for explicit-model calls)
  - `model_selection_reason` unknown
  - `social` SocialTaskIdentity
    - `platform` string, required
    - `operation_key` string, required
    - `operation_name` string, required
    - `schema_hash` string, required
  - `metadata` object, nullable
  - `input` object, nullable
  - `progress` AppApiV1SchemasCommonTaskProgress
    - `percent` integer, nullable
    - `stage` string, nullable
    - `message` string, nullable
  - `output` object, nullable
  - `warnings` TaskWarning[]
    - `code` string, required: e.g. option_clamped / auto_routed
    - `message` string, required
    - `field` string, nullable
  - `error` AppApiV1SchemasCommonTaskError
    - `code` string, required: Stable machine-readable public error code.
    - `type` string, required: Stable public error family.
    - `message` string, required: Human-readable safe failure reason.
    - `retryable` boolean, required: Whether the same logical request may succeed when retried unchanged.
    - `param` string, nullable: JSON Pointer to the relevant request or output field.
    - `details` object, nullable: Provider-neutral expected, received, supported, or candidate failure facts.
    - `request_id` string, required: Request trace identifier for support and correlation.
  - `usage` UsageObject
    - `input_tokens` integer, nullable
    - `output_tokens` integer, nullable
    - `cache_read_tokens` integer, nullable
    - `cache_creation_tokens` integer, nullable
    - `reasoning_tokens` integer, nullable
    - `image_count` integer, nullable
    - `image_pixels` integer, nullable
    - `video_seconds` number, nullable
    - `input_video_seconds` number, nullable: Authoritative input-video seconds included in settled video usage.
    - `output_video_seconds` number, nullable: Authoritative generated/output-video seconds included in settled video usage.
    - `audio_seconds` number, nullable
    - `characters` integer, nullable
    - `lines` UsageLine[]
      - `meter` string, required: e.g. input_token / output_token / image_count / input_video_second / output_video_second
      - `quantity` string, required: Decimal — number of meter units consumed
      - `unit` string, required: Display unit, e.g. 'token' / 'image' / 'second'
      - `billed_amount_credits` string, nullable: Credits charged for this usage line. Populated by PR-2/3.
    - `credits` string, nullable: Credits charged for this Task. Populated by PR-2 / PR-3.
  - `billing` TaskBilling
    - `charged_credits` string, nullable: Credits charged to wallet for this Task. Populated by PR-2/3.
    - `refunded_credits` string, nullable: Credits refunded for this Task. Populated by PR-3.
    - `granted_credits` string, nullable: Credits on this Task covered by a directed grant rather than by the wallet, net of any revocation. Absent when no grant applied.
    - `grant_source` string, nullable: Which grant covered it. Present exactly when granted_credits is.
    - `net_charged_credits` string, nullable: Final customer charge: charged_credits minus refunded_credits minus granted_credits. This is the number to report as what the Task cost.
  - `callback` TaskCallback
    - `url` string, required
    - `status` 'pending' | 'dispatching' | 'delivered' | 'retrying' | 'failed', required
    - `attempt_count` integer, required
    - `delivered_at` string, date-time, nullable
    - `last_error` string, nullable: Stable Beatra-owned callback delivery failure summary.
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable
  - `deadline_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `cancel_requested_at` string, date-time, nullable
  - `links` TaskLinks, required
    - `self` string, required
    - `cancel` string, nullable
    - `assets` string, nullable: Absolute customer-console URL for viewing and managing the generated artifacts.

## Other responses

- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/beatra/apis/agent-service-api.md) · [All operations](https://skmtc.dev/beatra/apis/agent-service-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beatra/apis/agent-service-api/revisions/58e440556498?raw)