Beatra

Transform one to four ordered reference images

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.

POST
/v1/images/image-to-image

Request Body

application/jsonRequired
metadataMetadata

Caller-supplied metadata; ≤16 keys, key ≤64 chars, value ≤512 chars

callback_urlCallback Url

HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state

callback_signing_key_idCallback Signing Key Id

Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided.

modelModel

Use auto for compatibility-based selection from the configured live candidates. A concrete model is evaluated exactly as requested and is never substituted.

Default: "auto"Value in: "auto" | "gpt-image-2" | "image-01" | "image-01-live" | "wan2.7-image-pro" | "wan2.7-image" | "qwen-image-2.0-pro" | "qwen-image-2.0"
prompt
Required
Prompt

Required prompt containing at least one non-whitespace character.

Minimum length: 1Pattern: "\\S"
countCount

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.

Default: 1Minimum: 1Maximum: 4
canvasCanvas

Desired output canvas. Preset source inherits the last input image's ratio; the omitted default is 2K at 16:9.

Default: {"type":"preset","tier":"2K","aspect":"16:9"}
seedSeed

Optional random seed. Supplying it constrains model eligibility; omit it for model-managed randomness.

negative_promptNegative Prompt

Optional content or qualities to avoid. Supplying it constrains model eligibility and is rejected when no compatible model is available.

enhance_promptEnhance Prompt

Omit or use null to retain the selected model's documented default; an explicit boolean constrains model eligibility.

palettePalette

Three to ten weighted RGB colors. Runtime validation requires the weights to sum exactly to 1.0000.

images
Required
Images

Ordered artifact, HTTPS URL, or data URI references.

output_relationshipImageOutputRelationship

Use independent for unrelated results, or sequence for a related image set. An explicit value constrains model eligibility and is rejected when unsupported.

Default: "independent"Value in: "independent" | "sequence"

Header Parameters

X-Request-Idstring

Optional client request id echoed in the response.

Idempotency-Key
Required
Idempotency-Key
Minimum length: 1Maximum length: 128
Authorization
Required
string

Bearer API key.

curl -X POST "https://example.com/v1/images/image-to-image" \
  -H "X-Request-Id: string" \
  -H "Idempotency-Key: string" \
  -H "Authorization: string" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "property1": "string",
      "property2": "string"
    },
    "callback_url": "string",
    "callback_signing_key_id": "string",
    "model": "auto",
    "prompt": "string",
    "count": 1,
    "canvas": {
      "type": "preset",
      "tier": "2K",
      "aspect": "16:9"
    },
    "seed": 2147483647,
    "negative_prompt": "string",
    "enhance_prompt": true,
    "palette": [
      {
        "color": "string",
        "weight": 1
      },
      {
        "color": "string",
        "weight": 1
      },
      {
        "color": "string",
        "weight": 1
      }
    ],
    "images": [
      {
        "type": "url",
        "url": "string"
      }
    ],
    "output_relationship": "independent"
  }'

Task accepted

{
  "object": "task",
  "task_id": "string",
  "status": "queued",
  "capability": "string",
  "model": "string",
  "resolved_model": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "input": {},
  "progress": {
    "percent": 100,
    "stage": "string",
    "message": "string"
  },
  "output": {},
  "warnings": [
    {
      "code": "string",
      "message": "string",
      "field": "string"
    }
  ],
  "error": {
    "code": "string",
    "type": "string",
    "message": "string",
    "retryable": true,
    "param": "string",
    "details": {},
    "request_id": "string"
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_tokens": 0,
    "cache_creation_tokens": 0,
    "reasoning_tokens": 0,
    "image_count": 0,
    "image_pixels": 0,
    "video_seconds": 0,
    "input_video_seconds": 0,
    "output_video_seconds": 0,
    "audio_seconds": 0,
    "characters": 0,
    "lines": [
      {
        "meter": "string",
        "quantity": "string",
        "unit": "string",
        "billed_amount_credits": "string"
      }
    ],
    "credits": "string"
  },
  "billing": {
    "charged_credits": "string",
    "refunded_credits": "string",
    "net_charged_credits": "string"
  },
  "callback": {
    "url": "string",
    "status": "pending",
    "attempt_count": 0,
    "delivered_at": "2019-08-24T14:15:22Z",
    "last_error": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "started_at": "2019-08-24T14:15:22Z",
  "deadline_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "cancel_requested_at": "2019-08-24T14:15:22Z",
  "links": {
    "self": "string",
    "cancel": "string"
  }
}