Documentation — RenderStack

The Problem Smart Cover Solves#

When using the standard cover fill mode, images are scaled to fill the frame and cropped from the center. This works well for simple compositions, but causes problems when:

A portrait photo placed in a wide frame has the subject's head cropped off
A group photo loses people at the edges
A product image has the product cut off by overlapping text or logos
The important content is not centered in the original image

Smart Cover analyzes the image content, finds the important subjects, and positions the image so those subjects align with a point you choose in the frame.

How It Works#

Select Smart Cover as the fill mode on an image element in the template editor
Set the focal anchor -- specify X% and Y% values to define exactly where in the frame the detected subject should appear (defaults to 50% / 50%, which is center-center)
At render time, the system:
- Detects faces, people, products, or other subjects in the provided image using AI vision
- Scales the image to cover the frame (same as standard cover)
- Offsets the image so the detected subject center aligns with your chosen focal anchor
- Clamps the offset so the frame is always fully covered (no empty space)
- For group photos, ensures the bounding box around all subjects stays visible

Setting Up Smart Cover in the Template Editor#

Step 1: Select an Image Element#

Click on any image element on the canvas to select it and open its properties panel.

Step 2: Choose Smart Cover Fill Mode#

In the properties panel, find the Fill Mode dropdown and select Smart Cover.

Step 3: Set the Focal Anchor#

When Smart Cover is selected, X% and Y% input fields appear below the fill mode dropdown:

X%: Horizontal position in the frame (0 = left edge, 50 = center, 100 = right edge)
Y%: Vertical position in the frame (0 = top edge, 50 = center, 100 = bottom edge)

The default is 50% X / 50% Y (center-center), which works well for most use cases. Adjust these values when part of the frame is covered by overlapping content and you need the subject positioned elsewhere.

Example scenarios:

Scenario	X%	Y%
General purpose (default)	50	50
Subject should appear slightly above center	50	40
Subject should favor the right side	60	50
Subject pushed toward bottom-right	70	70

Step 4: Preview#

A crosshair indicator appears on the canvas showing where the focal anchor is positioned. This helps you visualize where the detected subject will be placed relative to any overlapping content.

Using Smart Cover via API#

Basic Usage#

Set fillMode to smart-cover in the layer override. Use focalAnchorX and focalAnchorY to specify where in the frame the subject should appear:

{
  "template": "my-template",
  "layers": {
    "profile_photo": {
      "src": "https://example.com/photo.jpg",
      "fillMode": "smart-cover",
      "focalAnchorX": 50,
      "focalAnchorY": 50
    }
  }
}

focalAnchorX: 0 = left edge, 50 = center, 100 = right edge (default: 50)
focalAnchorY: 0 = top edge, 50 = center, 100 = bottom edge (default: 50)

If focalAnchorX and focalAnchorY are omitted, they default to 50 (center-center).

Legacy Named Anchors#

For backward compatibility, the following named anchor values are still supported via the focalAnchor property: top-left, top-center, top-right, center-left, center-center, center-right, bottom-left, bottom-center, bottom-right. However, using focalAnchorX and focalAnchorY is recommended for all new templates.

Pre-Computed Focal Point (Skip AI Detection)#

If you already know the subject's position, pass the coordinates directly to skip AI detection and speed up rendering:

{
  "layers": {
    "profile_photo": {
      "src": "https://example.com/photo.jpg",
      "fillMode": "smart-cover",
      "focalAnchorX": 50,
      "focalAnchorY": 50,
      "subjectCenterX": 48.5,
      "subjectCenterY": 32.1
    }
  }
}

subjectCenterX: Horizontal center of the subject as a percentage (0-100) of image width
subjectCenterY: Vertical center of the subject as a percentage (0-100) of image height

Group Photos with Bounding Box#

For images with multiple subjects (e.g., team photos), you can pass a bounding box to ensure all subjects remain visible:

{
  "layers": {
    "team_photo": {
      "src": "https://example.com/group.jpg",
      "fillMode": "smart-cover",
      "focalAnchorX": 50,
      "focalAnchorY": 50,
      "subjectCenterX": 50,
      "subjectCenterY": 35,
      "subjectBoundsX": 10,
      "subjectBoundsY": 15,
      "subjectBoundsWidth": 80,
      "subjectBoundsHeight": 45
    }
  }
}

subjectBoundsX: Left edge of the bounding box (percentage, 0-100)
subjectBoundsY: Top edge of the bounding box (percentage, 0-100)
subjectBoundsWidth: Width of the bounding box (percentage, 0-100)
subjectBoundsHeight: Height of the bounding box (percentage, 0-100)

The algorithm will position the image so that the entire bounding box fits within the frame whenever possible.

Pre-Analyzing Assets#

You can pre-analyze uploaded assets to detect focal points before render time. This stores the detection result in the asset metadata for instant use during rendering.

How to Pre-Analyze#

Use the asset analysis endpoint:

curl -X POST https://your-app.replit.app/api/assets/{assetId}/analyze-focal-point \
  -H "Authorization: Bearer YOUR_API_KEY"

The endpoint returns the detected focal point data:

{
  "focalX": 45.2,
  "focalY": 31.8,
  "boundingBox": {
    "x": 30.1,
    "y": 15.5,
    "width": 30.2,
    "height": 35.0
  },
  "subjectCount": 1,
  "confidence": 0.95,
  "primaryLabel": "face"
}

Once pre-analyzed, any render using that asset with Smart Cover will use the cached focal point data without making an additional AI call.

Detection and Caching#

How Detection Works#

The image is downloaded and resized to max 512px (to minimize AI processing cost)
The resized image is sent to an AI vision model that identifies subjects (faces, people, products, animals, etc.)
For each subject, the model returns a bounding box with center coordinates, dimensions, label, and confidence
For multi-subject images, a group bounding box is computed that encompasses all subjects
The focal point is the center of the group bounding box

Caching Strategy#

In-memory cache: The last 1,000 detection results are cached in memory for fast lookups
Database cache: Results are persisted in the database with a 30-day TTL
Asset metadata: Pre-analyzed assets store focal point data directly in their metadata
Cache key: Based on a SHA-256 hash of the image URL

The caching system means that the same image is only analyzed once, regardless of how many times it is rendered.

Warnings and Fallback Behavior#

Smart Cover may produce warnings in the render response:

Warning Code	Meaning
`SMART_FOCAL_FALLBACK`	AI detection failed (timeout, error, or low confidence). The image was positioned using standard center-center cover as a fallback.
`SMART_FOCAL_PARTIAL_CROP`	Some subjects may be partially cropped because the image aspect ratio does not allow all detected subjects to fit within the frame.
`SMART_COVER_NOT_AVAILABLE`	Smart Cover is not available on your current plan. The image was rendered using standard cover.
`SMART_COVER_LIMIT_REACHED`	Your monthly Smart Cover detection limit has been reached. Cached results still work, but new detections will fall back to center positioning.

When detection fails or is unavailable, Smart Cover always falls back gracefully to standard cover behavior with center-center positioning. The render still completes successfully.

Usage Limits#

Smart Cover detections count toward your plan's monthly AI detection limit:

Plan	Monthly Detections	Overage Behavior
Trial	100	Hard stop
Starter	Not available	N/A
Pro	200	Hard stop
Business	500	Overage charged
Enterprise	2,000	Overage charged

Important notes:

Cached results (from previous detections or pre-analyzed assets) do not count against your limit
Pre-computed coordinates passed via API do not count against your limit
Only new AI detection calls count toward the limit

Edge Cases and Tips#

Images Without Clear Subjects#

If the AI cannot identify a clear subject (e.g., abstract art, textures, landscapes without a focal point), it returns low confidence and Smart Cover falls back to center-center positioning.

Very Wide or Very Tall Subjects Relative to Frame#

When the subject bounding box is larger than what the frame can display at cover scale, the algorithm prioritizes frame coverage (no empty space) and issues a SMART_FOCAL_PARTIAL_CROP warning.

Multiple Subjects Spread Far Apart#

For group photos where subjects span most of the image width, the bounding box protection may conflict with the focal anchor positioning. Frame coverage always takes priority, and the algorithm does its best to keep all subjects visible.

Interaction with Percentage Reference Dimensions#

When template elements use percentage-based positioning (X, Y, Width, Height) alongside Smart Cover images, the reference dimension setting (width or height) affects how those elements reposition when the canvas aspect ratio changes at render time. For example, if a text overlay is pinned above a Smart Cover image using percentage offsets:

Width-based reference (default): The overlay's position resolves against canvas width, maintaining uniform spacing from edges regardless of aspect ratio changes. This pairs well with Smart Cover because both the overlay and the subject-aware image adapt predictably to different canvas sizes.
Height-based reference: The overlay's position resolves against canvas height, which may shift relative to the Smart Cover image's subject placement when the aspect ratio changes significantly.

If elements appear misaligned with Smart Cover subjects at non-native aspect ratios, check the percentRef setting on those elements' percentage properties. Using a consistent reference dimension (typically width) across related elements helps maintain their spatial relationship with the Smart Cover focal point.

Performance Considerations#

First render: May take 1-3 seconds longer due to AI detection
Subsequent renders: Cached results make Smart Cover as fast as standard cover
Pre-analysis recommended: For production workflows with known images, pre-analyze assets to eliminate any latency at render time
Pre-computed coordinates: Pass subjectCenterX/subjectCenterY via API for zero-latency positioning

Comparison with Other Fill Modes#

Fill Mode	Behavior	Best For
`cover`	Fills frame, crops excess from anchor point	Simple compositions, backgrounds
`smart-cover`	Fills frame, AI-positions subjects at focal anchor	Portraits, product photos, group shots
`contain`	Fits within frame, may letterbox	When showing the full image matters
`stretch`	Distorts to fill exact dimensions	Icons, patterns (aspect ratio unimportant)
`original`	Native size, no scaling	Pixel-perfect placements

Template Editor Guide -- Full editor documentation
Layer Management -- Managing dynamic and static layers
Rendering -- Render API reference
Assets -- Managing uploaded images and fonts
API Reference -- Complete API endpoint documentation

Smart Cover: AI-Powered Image Positioning