{"openapi":"3.1.0","info":{"title":"Bannerbear V5 API","version":"5.0"},"servers":[{"url":"https://api.bannerbear.com/v5"}],"security":[{"bearerAuth":[]}],"paths":{"/account":{"get":{"summary":"Get account info","responses":{"200":{"description":"Account details for the authenticated workspace and API key","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string","description":"Workspace UID"},"workspace":{"type":"string","description":"Workspace name"},"plan":{"type":"string","description":"Subscription plan"},"quota":{"type":"object","properties":{"max":{"type":"integer"},"current":{"type":"integer"},"remaining":{"type":"integer"}}},"api_key":{"type":"object","properties":{"name":{"type":"string","description":"API key name / identifier"},"permissions":{"type":"string","description":"API key permissions (e.g. read, read_write)"},"scope":{"type":"string","description":"API key scope"}}},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"/image_templates":{"get":{"summary":"List image templates","parameters":[{"name":"page","in":"query","schema":{"type":"integer"},"required":false}],"responses":{"200":{"description":"Paginated list of templates","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"width":{"type":"integer"},"height":{"type":"integer"},"adaptive":{"type":"boolean","description":"True if the template has adaptive sizing or positioning"},"preview":{"type":"string","nullable":true,"format":"uri","description":"Preview image URL"},"objects":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string"},"type":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"}}}}}}}}}},"/image_templates/{uid}":{"get":{"summary":"Get an image template","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Template details","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"width":{"type":"integer"},"height":{"type":"integer"},"adaptive":{"type":"boolean","description":"True if the template has adaptive sizing or positioning"},"preview":{"type":"string","nullable":true,"format":"uri","description":"Preview image URL"},"objects":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string"},"type":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"}}}}}}}},"patch":{"summary":"Update an image template","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Template name"},"description":{"type":"string","nullable":true,"description":"Template description"},"tags":{"type":"array","items":{"type":"string"},"description":"Template tags"}}}}}},"responses":{"200":{"description":"Updated template","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"width":{"type":"integer"},"height":{"type":"integer"},"adaptive":{"type":"boolean","description":"True if the template has adaptive sizing or positioning"},"preview":{"type":"string","nullable":true,"format":"uri","description":"Preview image URL"},"objects":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string"},"type":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"/images":{"get":{"summary":"List images","parameters":[{"name":"page","in":"query","schema":{"type":"integer"},"required":false}],"responses":{"200":{"description":"Paginated list of images","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"uid":{"type":"string"},"status":{"type":"string","enum":["pending","completed","failed"]},"template":{"type":"string"},"files":{"type":"object","description":"Output file URLs keyed by format"},"metadata":{"type":"string","nullable":true},"error":{"type":"string","nullable":true,"description":"Error message (only present on failure)"},"self":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"post":{"summary":"Create an image","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["template","modifications"],"properties":{"template":{"type":"string","description":"Template UID"},"modifications":{"type":"object","description":"Template and object modifications","properties":{"template":{"type":"object","description":"Template-level overrides","properties":{"width":{"type":"integer","description":"Override template width in pixels"},"height":{"type":"integer","description":"Override template height in pixels"},"transparent":{"type":"boolean","description":"Render with transparent background"}}},"objects":{"type":"array","description":"Array of object modifications","items":{"type":"object","properties":{"name":{"type":"string","description":"Layer name to target (use name or id, not both)"},"id":{"type":"string","description":"Layer ID to target (use name or id, not both)"},"left":{"description":"X position in pixels","type":"number"},"top":{"description":"Y position in pixels","type":"number"},"width":{"description":"Width in pixels","type":"number"},"height":{"description":"Height in pixels","type":"number"},"rotate":{"description":"Rotation angle in degrees","type":"number"},"rotateX":{"description":"3D rotation around the X axis in degrees","type":"number"},"rotateY":{"description":"3D rotation around the Y axis in degrees","type":"number"},"rotateZ":{"description":"3D rotation around the Z axis in degrees","type":"number"},"perspective":{"description":"Perspective distance for 3D transforms in pixels","type":"number"},"blur":{"description":"Gaussian blur radius in pixels","type":"number"},"opacity":{"description":"Opacity from 0 (transparent) to 1 (opaque)","type":"number"},"hidden":{"description":"Hide or show this layer","type":"boolean"},"padding":{"description":"Inner padding in pixels","type":"number"},"background-color":{"description":"Background color of the container","type":"string"},"box-shadow":{"description":"Box shadow in CSS format e.g. 2px 2px 4px #000","type":"string"},"border-style":{"description":"Border style: none or solid","type":"string","enum":["none","solid"]},"border-color":{"description":"Border color as hex, rgb, or named color","type":"string"},"border-width":{"description":"Border width in pixels","type":"number"},"anchor-point":{"description":"Which point on the target layer to anchor to","type":"string","enum":["top-left","top-center","top-right","center-left","center","center-right","bottom-left","bottom-center","bottom-right"]},"anchor-type":{"description":"Whether to anchor to the container bounds or text bounds","type":"string","enum":["container","text"]},"anchor-gap-x":{"description":"Horizontal offset from the anchor point in pixels","type":"number"},"anchor-gap-y":{"description":"Vertical offset from the anchor point in pixels","type":"number"},"adaptive-position":{"description":"How the layer repositions when the template is resized","type":"string","enum":["none","scale","pin-right","pin-bottom","pin-right-bottom"]},"adaptive-size":{"description":"How the layer resizes when the template is resized","type":"string","enum":["none","scale","stretch-x","stretch-y","stretch"]},"adaptive-aspect-ratio":{"description":"Whether the layer keeps its aspect ratio when adaptively resized","type":"string","enum":["free","locked"]},"adaptive-anchor-gap":{"description":"How the anchor gap adjusts when the template is resized","type":"string","enum":["none","scale","scale-x","scale-y","stretch","stretch-x","stretch-y"]},"text":{"description":"Text content to display","type":"string"},"color":{"description":"Text or fill color as hex, rgb, or named color","type":"string"},"text-highlight-color":{"description":"Background color behind individual lines of text","type":"string"},"text-highlight-padding-vertical":{"description":"Vertical padding around text highlight in pixels","type":"number"},"text-highlight-padding-horizontal":{"description":"Horizontal padding around text highlight in pixels","type":"number"},"text-background-image-mask":{"description":"Image URL to use as a clipping mask for the text fill","type":"string"},"font-size":{"description":"Font size in pixels","type":"number"},"font-weight":{"description":"Font weight from 100 (thin) to 900 (black)","type":"string","enum":[100,200,300,400,500,600,700,800,900]},"font-style":{"description":"Font style: normal or italic","type":"string","enum":["normal","italic"]},"line-height":{"description":"Line height multiplier for text spacing","type":"number"},"text-decoration":{"description":"Text decoration: none, underline, or overline","type":"string","enum":["none","underline","overline"]},"text-transform":{"description":"Text capitalization: none, uppercase, lowercase, or capitalize","type":"string","enum":["none","uppercase","lowercase","capitalize"]},"text-align":{"description":"Horizontal text alignment","type":"string","enum":["left","center","right","justify","start","end"]},"align-items":{"description":"Vertical text alignment within the container","type":"string","enum":["start","center","end"]},"direction":{"description":"Text direction: ltr (left-to-right) or rtl (right-to-left)","type":"string","enum":["ltr","rtl"]},"word-break":{"description":"Word breaking behavior for long words","type":"string","enum":["normal","break-all","keep-all","break-word"]},"white-space":{"description":"How whitespace and line breaks are handled","type":"string","enum":["normal","nowrap","pre","pre-wrap","pre-line"]},"letter-spacing":{"description":"Letter spacing in pixels","type":"number"},"skewX":{"description":"Horizontal skew angle in degrees","type":"number"},"skewY":{"description":"Vertical skew angle in degrees","type":"number"},"text-shadow":{"description":"Text shadow in CSS format e.g. 2px 2px 4px #000","type":"string"},"text-stroke-width":{"description":"Width of the text outline stroke in pixels","type":"number"},"text-stroke-color":{"description":"Color of the text outline stroke","type":"string"},"font-family-secondary":{"description":"Font family for text wrapped in *asterisks*","type":"string"},"color-secondary":{"description":"Text color for text wrapped in *asterisks*","type":"string"},"font-weight-secondary":{"description":"Font weight for text wrapped in *asterisks*","type":"string","enum":["",100,200,300,400,500,600,700,800,900]},"font-style-secondary":{"description":"Font style for text wrapped in *asterisks*","type":"string","enum":["","normal","italic"]},"text-transform-secondary":{"description":"Text transform for text wrapped in *asterisks*","type":"string","enum":["","none","uppercase","lowercase","capitalize"]},"text-decoration-secondary":{"description":"Text decoration for text wrapped in *asterisks*","type":"string","enum":["","none","underline","line-through"]},"text-fit":{"description":"How text is sized to fit its container","type":"string","enum":["off","auto_fit","resize_overflow"]},"text-ellipsis":{"description":"Truncate overflowing text with an ellipsis","type":"boolean"},"background-image":{"description":"Image URL to display in the container","type":"string"},"background-color-gradient":{"description":"Second color for a two-color gradient fill","type":"string"},"background-gradient-direction":{"description":"Direction of the gradient fill","type":"string","enum":["left","right","top","bottom"]},"background-size":{"description":"How the background image fills the container","type":"string","enum":["cover","contain"]},"background-blend-mode":{"description":"Blend mode applied to the background image","type":"string","enum":["normal","multiply","screen","overlay","darken","lighten","color-dodge","color-burn","hard-light","soft-light","difference","exclusion","hue","saturation","color","luminosity"]},"grayscale":{"description":"Grayscale filter intensity from 0 to 1","type":"number"},"sepia":{"description":"Sepia filter intensity from 0 to 1","type":"number"},"brightness":{"description":"Brightness adjustment where 1 is normal","type":"number"},"contrast":{"description":"Contrast adjustment where 1 is normal","type":"number"},"saturate":{"description":"Saturation adjustment where 1 is normal","type":"number"},"ai-detect":{"description":"AI detection mode for automatic image positioning","type":"string","enum":["off","face","subject"]},"ai-detect-focus":{"description":"Which detection to focus on when multiple are found","type":"string","enum":["first","largest","group"]},"ai-detect-on-fail":{"description":"Fallback background-size when no face or subject is detected","type":"string","enum":["fallback_cover","fallback_contain"]},"ai-detect-zoom":{"description":"Zoom level for AI detection crop","type":"string","enum":["auto","50%","60%","70%","80%","90%"]},"ai-detect-anchor":{"description":"Manual anchor point override for AI detection in x:y format (0-100)","type":"string"},"png-stroke-width":{"description":"Outline stroke width around PNG images in pixels","type":"number"},"png-stroke-color":{"description":"Outline stroke color around PNG images","type":"string"},"png-shadow":{"description":"Drop shadow for PNG images in CSS shadow format","type":"string"},"aspect-ratio-locked":{"description":"aspect-ratio-locked","type":"boolean"},"basic-shape":{"description":"The SVG shape to render","type":"string","enum":["triangle","scalene","pentagon","right","trapeze","kite","polygon","parallelogram","ellipse","trefoil","star","semicircle","hexagon","crescent","octagon","cross","ring","heart","arrow","rhombus"]},"fill":{"description":"Fill color of the shape","type":"string"},"stroke":{"description":"Stroke color of the shape outline","type":"string"},"stroke-width":{"description":"Stroke width of the shape outline in pixels","type":"number"},"qr-target":{"description":"URL or text content to encode in the QR code","type":"string"},"qr-color":{"description":"Foreground color of the QR code","type":"string"},"barcode-data":{"description":"Data to encode in the barcode","type":"string"},"barcode-format":{"description":"Barcode encoding format","type":"string","enum":["CODE128","EAN13","UPC","EAN8"]},"barcode-color":{"description":"Foreground color of the barcode","type":"string"},"rating-score":{"description":"Rating score from 0 to 100","type":"number"},"rating-shape":{"description":"Shape used for each rating unit","type":"string","enum":["star","cute_star","heart","circle","diamond","square","hexagon"]},"rating-count":{"description":"Number of shapes to display","type":"number"},"rating-color":{"description":"Fill color for active rating shapes","type":"string"},"rating-background-color":{"description":"Fill color for inactive rating shapes","type":"string"},"rating-gap":{"description":"Gap between rating shapes in pixels","type":"number"},"rating-stroke-color":{"description":"Outline stroke color for rating shapes","type":"string"},"rating-stroke-width":{"description":"Outline stroke width for rating shapes in pixels","type":"number"},"rating-shadow":{"description":"Drop shadow for rating shapes in CSS shadow format","type":"string"},"collapsed":{"description":"collapsed","type":"boolean"},"font-family":{"description":"Font family name (Google Fonts or custom font)","type":"string"},"border-radius":{"description":"Border radius in pixels for rounded corners","type":"number"}}}}}},"formats":{"type":"array","description":"Output file formats","default":["jpg"],"items":{"type":"string","enum":["jpg","png","pdf","webp","avif"]}},"scale":{"type":"integer","description":"Output scale multiplier for higher resolution","default":1,"enum":[1,2,3,4]},"dpi":{"type":"integer","description":"DPI metadata embedded in the output image for print sizing","minimum":72,"maximum":600},"quality":{"type":"integer","description":"Compression quality for JPG/WebP output","minimum":1,"maximum":100},"proxy":{"type":"boolean","description":"Proxy and resize external images before rendering","default":false},"metadata":{"type":"string","description":"Arbitrary metadata string stored with the image"},"version":{"type":"integer","description":"Target a specific template version number"}}}}}},"responses":{"202":{"description":"Image creation accepted","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"},"status":{"type":"string","enum":["pending","completed","failed"]},"template":{"type":"string"},"files":{"type":"object","description":"Output file URLs keyed by format"},"metadata":{"type":"string","nullable":true},"error":{"type":"string","nullable":true,"description":"Error message (only present on failure)"},"self":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"/images/{uid}":{"get":{"summary":"Get an image","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Image details","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"},"status":{"type":"string","enum":["pending","completed","failed"]},"template":{"type":"string"},"files":{"type":"object","description":"Output file URLs keyed by format"},"metadata":{"type":"string","nullable":true},"error":{"type":"string","nullable":true,"description":"Error message (only present on failure)"},"self":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"/batches":{"get":{"summary":"List batches","parameters":[{"name":"page","in":"query","schema":{"type":"integer"},"required":false}],"responses":{"200":{"description":"Paginated list of batches","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"uid":{"type":"string"},"type":{"type":"string","enum":["images"]},"status":{"type":"string","enum":["pending","completed"]},"total":{"type":"integer"},"counts":{"type":"object","properties":{"completed":{"type":"integer"},"failed":{"type":"integer"},"invalid":{"type":"integer"},"pending":{"type":"integer"}}},"errors":{"type":"array","items":{"type":"object"}},"items":{"type":"array","items":{"type":"object","properties":{"uid":{"type":"string"},"status":{"type":"string","enum":["pending","completed","failed"]},"template":{"type":"string"},"files":{"type":"object","description":"Output file URLs keyed by format"},"metadata":{"type":"string","nullable":true},"error":{"type":"string","nullable":true,"description":"Error message (only present on failure)"},"self":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}}},"self":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"post":{"summary":"Create a batch","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","items"],"properties":{"type":{"type":"string","enum":["images"],"description":"Batch type"},"items":{"type":"array","description":"Array of image payloads (max 100)","items":{"type":"object","required":["template","modifications"],"properties":{"template":{"type":"string","description":"Template UID"},"modifications":{"type":"object","description":"Template and object modifications","properties":{"template":{"type":"object","description":"Template-level overrides","properties":{"width":{"type":"integer","description":"Override template width in pixels"},"height":{"type":"integer","description":"Override template height in pixels"},"transparent":{"type":"boolean","description":"Render with transparent background"}}},"objects":{"type":"array","description":"Array of object modifications","items":{"type":"object","properties":{"name":{"type":"string","description":"Layer name to target (use name or id, not both)"},"id":{"type":"string","description":"Layer ID to target (use name or id, not both)"},"left":{"description":"X position in pixels","type":"number"},"top":{"description":"Y position in pixels","type":"number"},"width":{"description":"Width in pixels","type":"number"},"height":{"description":"Height in pixels","type":"number"},"rotate":{"description":"Rotation angle in degrees","type":"number"},"rotateX":{"description":"3D rotation around the X axis in degrees","type":"number"},"rotateY":{"description":"3D rotation around the Y axis in degrees","type":"number"},"rotateZ":{"description":"3D rotation around the Z axis in degrees","type":"number"},"perspective":{"description":"Perspective distance for 3D transforms in pixels","type":"number"},"blur":{"description":"Gaussian blur radius in pixels","type":"number"},"opacity":{"description":"Opacity from 0 (transparent) to 1 (opaque)","type":"number"},"hidden":{"description":"Hide or show this layer","type":"boolean"},"padding":{"description":"Inner padding in pixels","type":"number"},"background-color":{"description":"Background color of the container","type":"string"},"box-shadow":{"description":"Box shadow in CSS format e.g. 2px 2px 4px #000","type":"string"},"border-style":{"description":"Border style: none or solid","type":"string","enum":["none","solid"]},"border-color":{"description":"Border color as hex, rgb, or named color","type":"string"},"border-width":{"description":"Border width in pixels","type":"number"},"anchor-point":{"description":"Which point on the target layer to anchor to","type":"string","enum":["top-left","top-center","top-right","center-left","center","center-right","bottom-left","bottom-center","bottom-right"]},"anchor-type":{"description":"Whether to anchor to the container bounds or text bounds","type":"string","enum":["container","text"]},"anchor-gap-x":{"description":"Horizontal offset from the anchor point in pixels","type":"number"},"anchor-gap-y":{"description":"Vertical offset from the anchor point in pixels","type":"number"},"adaptive-position":{"description":"How the layer repositions when the template is resized","type":"string","enum":["none","scale","pin-right","pin-bottom","pin-right-bottom"]},"adaptive-size":{"description":"How the layer resizes when the template is resized","type":"string","enum":["none","scale","stretch-x","stretch-y","stretch"]},"adaptive-aspect-ratio":{"description":"Whether the layer keeps its aspect ratio when adaptively resized","type":"string","enum":["free","locked"]},"adaptive-anchor-gap":{"description":"How the anchor gap adjusts when the template is resized","type":"string","enum":["none","scale","scale-x","scale-y","stretch","stretch-x","stretch-y"]},"text":{"description":"Text content to display","type":"string"},"color":{"description":"Text or fill color as hex, rgb, or named color","type":"string"},"text-highlight-color":{"description":"Background color behind individual lines of text","type":"string"},"text-highlight-padding-vertical":{"description":"Vertical padding around text highlight in pixels","type":"number"},"text-highlight-padding-horizontal":{"description":"Horizontal padding around text highlight in pixels","type":"number"},"text-background-image-mask":{"description":"Image URL to use as a clipping mask for the text fill","type":"string"},"font-size":{"description":"Font size in pixels","type":"number"},"font-weight":{"description":"Font weight from 100 (thin) to 900 (black)","type":"string","enum":[100,200,300,400,500,600,700,800,900]},"font-style":{"description":"Font style: normal or italic","type":"string","enum":["normal","italic"]},"line-height":{"description":"Line height multiplier for text spacing","type":"number"},"text-decoration":{"description":"Text decoration: none, underline, or overline","type":"string","enum":["none","underline","overline"]},"text-transform":{"description":"Text capitalization: none, uppercase, lowercase, or capitalize","type":"string","enum":["none","uppercase","lowercase","capitalize"]},"text-align":{"description":"Horizontal text alignment","type":"string","enum":["left","center","right","justify","start","end"]},"align-items":{"description":"Vertical text alignment within the container","type":"string","enum":["start","center","end"]},"direction":{"description":"Text direction: ltr (left-to-right) or rtl (right-to-left)","type":"string","enum":["ltr","rtl"]},"word-break":{"description":"Word breaking behavior for long words","type":"string","enum":["normal","break-all","keep-all","break-word"]},"white-space":{"description":"How whitespace and line breaks are handled","type":"string","enum":["normal","nowrap","pre","pre-wrap","pre-line"]},"letter-spacing":{"description":"Letter spacing in pixels","type":"number"},"skewX":{"description":"Horizontal skew angle in degrees","type":"number"},"skewY":{"description":"Vertical skew angle in degrees","type":"number"},"text-shadow":{"description":"Text shadow in CSS format e.g. 2px 2px 4px #000","type":"string"},"text-stroke-width":{"description":"Width of the text outline stroke in pixels","type":"number"},"text-stroke-color":{"description":"Color of the text outline stroke","type":"string"},"font-family-secondary":{"description":"Font family for text wrapped in *asterisks*","type":"string"},"color-secondary":{"description":"Text color for text wrapped in *asterisks*","type":"string"},"font-weight-secondary":{"description":"Font weight for text wrapped in *asterisks*","type":"string","enum":["",100,200,300,400,500,600,700,800,900]},"font-style-secondary":{"description":"Font style for text wrapped in *asterisks*","type":"string","enum":["","normal","italic"]},"text-transform-secondary":{"description":"Text transform for text wrapped in *asterisks*","type":"string","enum":["","none","uppercase","lowercase","capitalize"]},"text-decoration-secondary":{"description":"Text decoration for text wrapped in *asterisks*","type":"string","enum":["","none","underline","line-through"]},"text-fit":{"description":"How text is sized to fit its container","type":"string","enum":["off","auto_fit","resize_overflow"]},"text-ellipsis":{"description":"Truncate overflowing text with an ellipsis","type":"boolean"},"background-image":{"description":"Image URL to display in the container","type":"string"},"background-color-gradient":{"description":"Second color for a two-color gradient fill","type":"string"},"background-gradient-direction":{"description":"Direction of the gradient fill","type":"string","enum":["left","right","top","bottom"]},"background-size":{"description":"How the background image fills the container","type":"string","enum":["cover","contain"]},"background-blend-mode":{"description":"Blend mode applied to the background image","type":"string","enum":["normal","multiply","screen","overlay","darken","lighten","color-dodge","color-burn","hard-light","soft-light","difference","exclusion","hue","saturation","color","luminosity"]},"grayscale":{"description":"Grayscale filter intensity from 0 to 1","type":"number"},"sepia":{"description":"Sepia filter intensity from 0 to 1","type":"number"},"brightness":{"description":"Brightness adjustment where 1 is normal","type":"number"},"contrast":{"description":"Contrast adjustment where 1 is normal","type":"number"},"saturate":{"description":"Saturation adjustment where 1 is normal","type":"number"},"ai-detect":{"description":"AI detection mode for automatic image positioning","type":"string","enum":["off","face","subject"]},"ai-detect-focus":{"description":"Which detection to focus on when multiple are found","type":"string","enum":["first","largest","group"]},"ai-detect-on-fail":{"description":"Fallback background-size when no face or subject is detected","type":"string","enum":["fallback_cover","fallback_contain"]},"ai-detect-zoom":{"description":"Zoom level for AI detection crop","type":"string","enum":["auto","50%","60%","70%","80%","90%"]},"ai-detect-anchor":{"description":"Manual anchor point override for AI detection in x:y format (0-100)","type":"string"},"png-stroke-width":{"description":"Outline stroke width around PNG images in pixels","type":"number"},"png-stroke-color":{"description":"Outline stroke color around PNG images","type":"string"},"png-shadow":{"description":"Drop shadow for PNG images in CSS shadow format","type":"string"},"aspect-ratio-locked":{"description":"aspect-ratio-locked","type":"boolean"},"basic-shape":{"description":"The SVG shape to render","type":"string","enum":["triangle","scalene","pentagon","right","trapeze","kite","polygon","parallelogram","ellipse","trefoil","star","semicircle","hexagon","crescent","octagon","cross","ring","heart","arrow","rhombus"]},"fill":{"description":"Fill color of the shape","type":"string"},"stroke":{"description":"Stroke color of the shape outline","type":"string"},"stroke-width":{"description":"Stroke width of the shape outline in pixels","type":"number"},"qr-target":{"description":"URL or text content to encode in the QR code","type":"string"},"qr-color":{"description":"Foreground color of the QR code","type":"string"},"barcode-data":{"description":"Data to encode in the barcode","type":"string"},"barcode-format":{"description":"Barcode encoding format","type":"string","enum":["CODE128","EAN13","UPC","EAN8"]},"barcode-color":{"description":"Foreground color of the barcode","type":"string"},"rating-score":{"description":"Rating score from 0 to 100","type":"number"},"rating-shape":{"description":"Shape used for each rating unit","type":"string","enum":["star","cute_star","heart","circle","diamond","square","hexagon"]},"rating-count":{"description":"Number of shapes to display","type":"number"},"rating-color":{"description":"Fill color for active rating shapes","type":"string"},"rating-background-color":{"description":"Fill color for inactive rating shapes","type":"string"},"rating-gap":{"description":"Gap between rating shapes in pixels","type":"number"},"rating-stroke-color":{"description":"Outline stroke color for rating shapes","type":"string"},"rating-stroke-width":{"description":"Outline stroke width for rating shapes in pixels","type":"number"},"rating-shadow":{"description":"Drop shadow for rating shapes in CSS shadow format","type":"string"},"collapsed":{"description":"collapsed","type":"boolean"},"font-family":{"description":"Font family name (Google Fonts or custom font)","type":"string"},"border-radius":{"description":"Border radius in pixels for rounded corners","type":"number"}}}}}},"formats":{"type":"array","description":"Output file formats","default":["jpg"],"items":{"type":"string","enum":["jpg","png","pdf","webp","avif"]}},"scale":{"type":"integer","description":"Output scale multiplier for higher resolution","default":1,"enum":[1,2,3,4]},"dpi":{"type":"integer","description":"DPI metadata embedded in the output image for print sizing","minimum":72,"maximum":600},"quality":{"type":"integer","description":"Compression quality for JPG/WebP output","minimum":1,"maximum":100},"proxy":{"type":"boolean","description":"Proxy and resize external images before rendering","default":false},"metadata":{"type":"string","description":"Arbitrary metadata string stored with the image"},"version":{"type":"integer","description":"Target a specific template version number"}}}}}}}}},"responses":{"202":{"description":"Batch creation accepted","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"},"type":{"type":"string","enum":["images"]},"status":{"type":"string","enum":["pending","completed"]},"total":{"type":"integer"},"counts":{"type":"object","properties":{"completed":{"type":"integer"},"failed":{"type":"integer"},"invalid":{"type":"integer"},"pending":{"type":"integer"}}},"errors":{"type":"array","items":{"type":"object"}},"items":{"type":"array","items":{"type":"object","properties":{"uid":{"type":"string"},"status":{"type":"string","enum":["pending","completed","failed"]},"template":{"type":"string"},"files":{"type":"object","description":"Output file URLs keyed by format"},"metadata":{"type":"string","nullable":true},"error":{"type":"string","nullable":true,"description":"Error message (only present on failure)"},"self":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}}},"self":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"/batches/{uid}":{"get":{"summary":"Get a batch","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Batch details","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"},"type":{"type":"string","enum":["images"]},"status":{"type":"string","enum":["pending","completed"]},"total":{"type":"integer"},"counts":{"type":"object","properties":{"completed":{"type":"integer"},"failed":{"type":"integer"},"invalid":{"type":"integer"},"pending":{"type":"integer"}}},"errors":{"type":"array","items":{"type":"object"}},"items":{"type":"array","items":{"type":"object","properties":{"uid":{"type":"string"},"status":{"type":"string","enum":["pending","completed","failed"]},"template":{"type":"string"},"files":{"type":"object","description":"Output file URLs keyed by format"},"metadata":{"type":"string","nullable":true},"error":{"type":"string","nullable":true,"description":"Error message (only present on failure)"},"self":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}}},"self":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"/webhooks":{"get":{"summary":"List webhooks","parameters":[{"name":"page","in":"query","schema":{"type":"integer"},"required":false}],"responses":{"200":{"description":"Paginated list of webhooks","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"resource":{"type":"string","enum":["image","batch"]},"event":{"type":"string","enum":["all_events","completed","failed"]},"status":{"type":"string","enum":["active","disabled"]},"scope":{"type":"string","enum":["all_templates","specific_templates"]},"templates":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Template UIDs (only when scope is specific_templates)"},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"post":{"summary":"Create a webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string","description":"Webhook name"},"url":{"type":"string","format":"uri","description":"URL to receive webhook events"},"resource":{"type":"string","enum":["image","batch"],"description":"Resource type to trigger on"},"event":{"type":"string","enum":["all_events","completed","failed"],"description":"Event type to trigger on"},"status":{"type":"string","enum":["active","disabled"],"description":"Webhook status"},"scope":{"type":"string","enum":["all_templates","specific_templates"],"description":"Template scope"},"templates":{"type":"array","items":{"type":"string"},"description":"Template UIDs (when scope is specific_templates)"}}}}}},"responses":{"201":{"description":"Webhook created. The signing_key field is only returned here — store it now.","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"resource":{"type":"string","enum":["image","batch"]},"event":{"type":"string","enum":["all_events","completed","failed"]},"status":{"type":"string","enum":["active","disabled"]},"scope":{"type":"string","enum":["all_templates","specific_templates"]},"templates":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Template UIDs (only when scope is specific_templates)"},"created_at":{"type":"string","format":"date-time"},"signing_key":{"type":"string","description":"HMAC signing key. Only returned at creation time — store it now."}}}}}}}}},"/webhooks/{uid}":{"get":{"summary":"Get a webhook","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook details","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"resource":{"type":"string","enum":["image","batch"]},"event":{"type":"string","enum":["all_events","completed","failed"]},"status":{"type":"string","enum":["active","disabled"]},"scope":{"type":"string","enum":["all_templates","specific_templates"]},"templates":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Template UIDs (only when scope is specific_templates)"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"patch":{"summary":"Update a webhook","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string","description":"Webhook name"},"url":{"type":"string","format":"uri","description":"URL to receive webhook events"},"resource":{"type":"string","enum":["image","batch"],"description":"Resource type to trigger on"},"event":{"type":"string","enum":["all_events","completed","failed"],"description":"Event type to trigger on"},"status":{"type":"string","enum":["active","disabled"],"description":"Webhook status"},"scope":{"type":"string","enum":["all_templates","specific_templates"],"description":"Template scope"},"templates":{"type":"array","items":{"type":"string"},"description":"Template UIDs (when scope is specific_templates)"}}}}}},"responses":{"200":{"description":"Updated webhook","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"resource":{"type":"string","enum":["image","batch"]},"event":{"type":"string","enum":["all_events","completed","failed"]},"status":{"type":"string","enum":["active","disabled"]},"scope":{"type":"string","enum":["all_templates","specific_templates"]},"templates":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Template UIDs (only when scope is specific_templates)"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"delete":{"summary":"Delete a webhook","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook deleted"}}}},"/instant_urls":{"get":{"summary":"List instant URLs","parameters":[{"name":"page","in":"query","schema":{"type":"integer"},"required":false}],"responses":{"200":{"description":"Paginated list of instant URLs","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"template":{"type":"string","description":"Source image template UID"},"template_version":{"type":"integer","nullable":true,"description":"Pinned template version, or null for latest"},"mode":{"type":"string","enum":["encoded","named_params"]},"security":{"type":"string","enum":["signed","open"]},"status":{"type":"string","enum":["active","disabled"]},"scale":{"type":"integer","enum":[1,2,3,4]},"rate_limit":{"type":"boolean","description":"Whether per-IP rate limiting is enabled"},"max_renders":{"type":"integer","nullable":true},"render_count":{"type":"integer"},"expires_at":{"type":"string","format":"date-time","nullable":true},"base_url":{"type":"string","format":"uri"},"sample_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"post":{"summary":"Create an instant URL","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","template"],"properties":{"name":{"type":"string"},"template":{"type":"string","description":"Image template UID this Instant URL is bound to"},"mode":{"type":"string","enum":["encoded","named_params"]},"security":{"type":"string","enum":["signed","open"]},"status":{"type":"string","enum":["active","disabled"]},"scale":{"type":"integer","enum":[1,2,3,4]},"rate_limit":{"type":"boolean"},"template_version":{"type":"integer","nullable":true},"max_renders":{"type":"integer","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true}}}}}},"responses":{"201":{"description":"Instant URL created. The signing_key field is only returned here — store it now.","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"template":{"type":"string","description":"Source image template UID"},"template_version":{"type":"integer","nullable":true,"description":"Pinned template version, or null for latest"},"mode":{"type":"string","enum":["encoded","named_params"]},"security":{"type":"string","enum":["signed","open"]},"status":{"type":"string","enum":["active","disabled"]},"scale":{"type":"integer","enum":[1,2,3,4]},"rate_limit":{"type":"boolean","description":"Whether per-IP rate limiting is enabled"},"max_renders":{"type":"integer","nullable":true},"render_count":{"type":"integer"},"expires_at":{"type":"string","format":"date-time","nullable":true},"base_url":{"type":"string","format":"uri"},"sample_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"signing_key":{"type":"string","description":"HMAC signing key. Only returned at creation time — store it now."}}}}}}}}},"/instant_urls/{uid}":{"get":{"summary":"Get an instant URL","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Instant URL details","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"template":{"type":"string","description":"Source image template UID"},"template_version":{"type":"integer","nullable":true,"description":"Pinned template version, or null for latest"},"mode":{"type":"string","enum":["encoded","named_params"]},"security":{"type":"string","enum":["signed","open"]},"status":{"type":"string","enum":["active","disabled"]},"scale":{"type":"integer","enum":[1,2,3,4]},"rate_limit":{"type":"boolean","description":"Whether per-IP rate limiting is enabled"},"max_renders":{"type":"integer","nullable":true},"render_count":{"type":"integer"},"expires_at":{"type":"string","format":"date-time","nullable":true},"base_url":{"type":"string","format":"uri"},"sample_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"patch":{"summary":"Update an instant URL","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","template"],"properties":{"name":{"type":"string"},"template":{"type":"string","description":"Image template UID this Instant URL is bound to"},"mode":{"type":"string","enum":["encoded","named_params"]},"security":{"type":"string","enum":["signed","open"]},"status":{"type":"string","enum":["active","disabled"]},"scale":{"type":"integer","enum":[1,2,3,4]},"rate_limit":{"type":"boolean"},"template_version":{"type":"integer","nullable":true},"max_renders":{"type":"integer","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true}}}}}},"responses":{"200":{"description":"Updated instant URL","content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"template":{"type":"string","description":"Source image template UID"},"template_version":{"type":"integer","nullable":true,"description":"Pinned template version, or null for latest"},"mode":{"type":"string","enum":["encoded","named_params"]},"security":{"type":"string","enum":["signed","open"]},"status":{"type":"string","enum":["active","disabled"]},"scale":{"type":"integer","enum":[1,2,3,4]},"rate_limit":{"type":"boolean","description":"Whether per-IP rate limiting is enabled"},"max_renders":{"type":"integer","nullable":true},"render_count":{"type":"integer"},"expires_at":{"type":"string","format":"date-time","nullable":true},"base_url":{"type":"string","format":"uri"},"sample_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"delete":{"summary":"Delete an instant URL","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Instant URL deleted"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (e.g. bb_ak_v5_...)"}}}}