Beatra

Edit a base image with optional references and regions

Create an asynchronous edit task where `images[0]` is the base image and later images are ordered references. Optional normalized regions target inputs by index. `auto` selects a compatible live model; a concrete model is never substituted.

POST
/v1/images/edits

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. The default is a 2K tier derived from the first base image's ratio; actual output dimensions remain authoritative.

Default: {"type":"preset","tier":"2K","aspect":"source"}
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 inputs; images[0] is the base and later entries are references.

edit_regionsEdit Regions

Flat normalized rectangles keyed by an input image_index. Runtime validation enforces cross-coordinate and collection relations.

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/edits" \
  -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": "source"
    },
    "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"
      }
    ],
    "edit_regions": [
      {
        "image_index": 0,
        "x": 0,
        "y": 0,
        "width": 1,
        "height": 1
      }
    ]
  }'

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"
  }
}