---
title: "Create an image"
method: POST
path: "/images"
---

# Create an image

`POST /images`

Create an image render. Async on api.bannerbear.com (returns 202 + pending record, poll via GET /images/{uid} or subscribe via webhook). Sync on sync.api.bannerbear.com (returns 200 + completed image inline, or 408 if the render exceeds the sync timeout).

## Request body

- ImageCreateRequest
  - `template` string, required — Template UID
  - `modifications` object, required — Template and object modifications
    - `template` object — Template-level overrides
      - `width` integer — Override template width in pixels
      - `height` integer — Override template height in pixels
      - `transparent` boolean — Render with transparent background
    - `objects` object[] — Array of object modifications
      - `name` string — Layer name to target (use name or id, not both)
      - `id` string — Layer ID to target (use name or id, not both)
      - `left` number — X position in pixels
      - `top` number — Y position in pixels
      - `width` number — Width in pixels
      - `height` number — Height in pixels
      - `rotate` number — Rotation angle in degrees
      - `rotateX` number — 3D rotation around the X axis in degrees
      - `rotateY` number — 3D rotation around the Y axis in degrees
      - `rotateZ` number — 3D rotation around the Z axis in degrees
      - `perspective` number — Perspective distance for 3D transforms in pixels
      - `blur` number — Gaussian blur radius in pixels
      - `opacity` number — Opacity from 0 (transparent) to 1 (opaque)
      - `hidden` boolean — Hide or show this layer
      - `padding` number — Inner padding in pixels
      - `background-color` string — Background color of the container
      - `box-shadow` string — Box shadow in CSS format e.g. 2px 2px 4px #000
      - `border-style` 'none' | 'solid' — Border style: none or solid
      - `border-color` string — Border color as hex, rgb, or named color
      - `border-width` number — Border width in pixels
      - `anchor-point` 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' — Which point on the target layer to anchor to
      - `anchor-type` 'container' | 'text' — Whether to anchor to the container bounds or text bounds
      - `anchor-gap-x` number — Horizontal offset from the anchor point in pixels
      - `anchor-gap-y` number — Vertical offset from the anchor point in pixels
      - `responsive-position` 'none' | 'scale' | 'center-x' | 'center-y' | 'center' | 'pin-right' | 'pin-bottom' | 'pin-right-bottom' — How the layer repositions when the template is resized
      - `responsive-size` 'none' | 'scale' | 'stretch-x' | 'stretch-y' | 'stretch' — How the layer resizes when the template is resized
      - `responsive-aspect-ratio` 'free' | 'locked' — Whether the layer keeps its aspect ratio when responsively resized
      - `responsive-anchor-gap` 'none' | 'scale' | 'scale-x' | 'scale-y' | 'stretch' | 'stretch-x' | 'stretch-y' — How the anchor gap adjusts when the template is resized
      - `text` string — Text content to display
      - `color` string — Text or fill color as hex, rgb, or named color
      - `text-highlight-color` string — Background color behind individual lines of text
      - `text-highlight-padding-vertical` number — Vertical padding around text highlight in pixels
      - `text-highlight-padding-horizontal` number — Horizontal padding around text highlight in pixels
      - `text-highlight-border-radius` number — Corner radius of the text highlight in pixels
      - `text-background-image-mask` string — Image URL to use as a clipping mask for the text fill
      - `font-size` number — Font size in pixels
      - `font-weight` 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 — Font weight from 100 (thin) to 900 (black)
      - `font-style` 'normal' | 'italic' — Font style: normal or italic
      - `line-height` number — Line height multiplier for text spacing
      - `text-decoration` 'none' | 'underline' | 'overline' — Text decoration: none, underline, or overline
      - `text-transform` 'none' | 'uppercase' | 'lowercase' | 'capitalize' — Text capitalization: none, uppercase, lowercase, or capitalize
      - `text-align` 'left' | 'center' | 'right' | 'justify' | 'start' | 'end' — Horizontal text alignment
      - `align-items` 'start' | 'center' | 'end' — Vertical text alignment within the container
      - `direction` 'ltr' | 'rtl' — Text direction: ltr (left-to-right) or rtl (right-to-left)
      - `word-break` 'normal' | 'break-all' | 'keep-all' | 'break-word' — Word breaking behavior for long words
      - `white-space` 'normal' | 'nowrap' | 'pre' | 'pre-wrap' | 'pre-line' — How whitespace and line breaks are handled
      - `letter-spacing` number — Letter spacing in pixels
      - `skewX` number — Horizontal skew angle in degrees
      - `skewY` number — Vertical skew angle in degrees
      - `text-shadow` string — Text shadow in CSS format e.g. 2px 2px 4px #000
      - `text-stroke-width` number — Width of the text outline stroke in pixels
      - `text-stroke-color` string — Color of the text outline stroke
      - `font-family-secondary` string — Font family for text wrapped in *asterisks*
      - `color-secondary` string — Text color for text wrapped in *asterisks*
      - `font-weight-secondary` 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900, nullable — Font weight for text wrapped in *asterisks*
      - `font-style-secondary` 'normal' | 'italic', nullable — Font style for text wrapped in *asterisks*
      - `text-transform-secondary` 'none' | 'uppercase' | 'lowercase' | 'capitalize', nullable — Text transform for text wrapped in *asterisks*
      - `text-decoration-secondary` 'none' | 'underline' | 'line-through', nullable — Text decoration for text wrapped in *asterisks*
      - `text-fit` 'off' | 'auto_fit' | 'resize_overflow' — How text is sized to fit its container
      - `text-ellipsis` boolean — Truncate overflowing text with an ellipsis
      - `background-color-gradient` string — Second color for a two-color gradient fill
      - `background-gradient-direction` 'left' | 'right' | 'top' | 'bottom' — Direction of the gradient fill
      - `background-image` string — Image URL to display in the container
      - `background-size` 'cover' | 'contain' — How the background image fills the container
      - `background-position` 'center' | 'top' | 'right' | 'bottom' | 'left' | 'top left' | 'top right' | 'bottom left' | 'bottom right' — Anchor position for the background image within the container — most useful when background-size is contain
      - `background-blend-mode` 'normal' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity' — Blend mode applied to the background image
      - `grayscale` number — Grayscale filter intensity from 0 to 1
      - `sepia` number — Sepia filter intensity from 0 to 1
      - `brightness` number — Brightness adjustment where 1 is normal
      - `contrast` number — Contrast adjustment where 1 is normal
      - `saturate` number — Saturation adjustment where 1 is normal
      - `ai-detect` 'off' | 'face' | 'subject' — AI detection mode for automatic image positioning
      - `ai-detect-focus` 'first' | 'largest' | 'group' — Which detection to focus on when multiple are found
      - `ai-detect-on-fail` 'fallback_cover' | 'fallback_contain' — Fallback background-size when no face or subject is detected
      - `ai-detect-zoom` 'auto' | '50%' | '60%' | '70%' | '80%' | '90%' — Zoom level for AI detection crop
      - `ai-detect-anchor` string — Manual anchor point override for AI detection in x:y format (0-100)
      - `ai-background-remove` 'disabled' | 'enabled' — Whether to automatically remove the background of images submitted to this container via the API
      - `ai-background-generate` 'disabled' | 'enabled' — Whether the container should generate its background image via AI when an ai-prompt is supplied in the API request
      - `ai-prompt` string — Prompt for AI background generation — applies when the layer has ai-background-generate enabled
      - `png-stroke-width` number — Outline stroke width around PNG images in pixels
      - `png-stroke-color` string — Outline stroke color around PNG images
      - `png-shadow` string — Drop shadow for PNG images in CSS shadow format
      - `aspect-ratio-locked` boolean — aspect-ratio-locked
      - `basic-shape` 'triangle' | 'scalene' | 'pentagon' | 'right' | 'trapeze' | 'kite' | 'polygon' | 'parallelogram' | 'ellipse' | 'trefoil' | 'star' | 'semicircle' | 'hexagon' | 'crescent' | 'octagon' | 'cross' | 'ring' | 'heart' | 'arrow' | 'rhombus' — The SVG shape to render
      - `fill` string — Fill color of the shape
      - `stroke` string — Stroke color of the shape outline
      - `stroke-width` number — Stroke width of the shape outline in pixels
      - `qr-target` string — URL or text content to encode in the QR code
      - `qr-color` string — Foreground color of the QR code
      - `barcode-data` string — Data to encode in the barcode
      - `barcode-format` 'CODE128' | 'EAN13' | 'UPC' | 'EAN8' — Barcode encoding format
      - `barcode-color` string — Foreground color of the barcode
      - `rating-score` number — Rating score from 0 to 100
      - `rating-shape` 'star' | 'cute_star' | 'heart' | 'circle' | 'diamond' | 'square' | 'hexagon' — Shape used for each rating unit
      - `rating-count` number — Number of shapes to display
      - `rating-color` string — Fill color for active rating shapes
      - `rating-background-color` string — Fill color for inactive rating shapes
      - `rating-gap` number — Gap between rating shapes in pixels
      - `rating-stroke-color` string — Outline stroke color for rating shapes
      - `rating-stroke-width` number — Outline stroke width for rating shapes in pixels
      - `rating-shadow` string — Drop shadow for rating shapes in CSS shadow format
      - `lottie-url` string — URL of the Lottie JSON file to play
      - `lottie-delay` number — Milliseconds to wait after the animation starts before this Lottie begins playing
      - `lottie-loop` boolean — Whether the Lottie repeats when it reaches its end, rather than holding its last frame
      - `collapsed` boolean — collapsed
      - `font-family` string — Font family name (Google Fonts or custom font)
      - `border-radius` number — Border radius in pixels for rounded corners
  - `formats` string[] — Output file formats
  - `scale` 1 | 2 | 3 | 4 — Output scale multiplier for higher resolution
  - `dpi` integer — DPI metadata embedded in the output image for print sizing
  - `quality` integer — Compression quality for JPG/WebP output
  - `proxy` boolean — Proxy and resize external images before rendering
  - `metadata` string — Arbitrary metadata string stored with the image
  - `version` integer — Target a specific template version number

## Response `200`

Sync render complete (sync host only)

- object
  - `uid` string
  - `status` 'pending' | 'completed' | 'failed'
  - `template` string
  - `files` object — Output file URLs keyed by format
  - `metadata` string, nullable
  - `error` string, nullable — Error message (only present on failure)
  - `self` string, uri
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable

## Other responses

- `202` — Async render accepted (async host only)
- `402` — API quota exhausted — upgrade required
- `403` — API key does not have access to this template
- `404` — Template not found in this workspace
- `408` — Sync render timed out (sync host only)
- `422` — Payload validation failure — e.g. invalid modification, unknown attribute, bad option value

---

[API](https://skmtc.dev/bannerbear/apis/bannerbear-v5-api.md) · [All operations](https://skmtc.dev/bannerbear/apis/bannerbear-v5-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bannerbear/bannerbear-v5-api/revisions/6aa425420a10/schema)