Primary backgrounds (pick exactly one)

#The rule

Among colorBg, gradientBg, customBg, videoBg, and transparentBase: true, activate only one primary background per call.

If multiple primary backgrounds are configured, createCanvas rejects the configuration before painting.

#Option A — Solid color (colorBg)

1await painter.createCanvas({2  width: 800,3  height: 450,4  colorBg: '#0f172a',5});

Special: colorBg: 'transparent' skips painting opaque color on that branch (often paired with transparent base or layers).

#Option B — Gradient (gradientBg)

Uses GradientConfig: linear, radial, or conic with colors stops.

1await painter.createCanvas({2  width: 900,3  height: 500,4  gradientBg: {5    type: 'linear',6    startX: 0,7    startY: 0,8    endX: 900,9    endY: 500,10    colors: [11      { stop: 0, color: '#312e81' },12      { stop: 1, color: '#1e1b4b' },13    ],14  },15});

#Option C — Image (customBg)

1await painter.createCanvas({2  width: 1200,3  height: 630,4  customBg: {5    source: './assets/hero.jpg',6    fit: 'cover',7    align: 'center',8  },9});

#Option D — Video frame (videoBg)

Requires FFmpeg. Apexify extracts one still frame once, then renders that still through the same image-background placement/filter pipeline as customBg.

If neither frame nor time is supplied, Apexify selects frame 1. Legacy loop and autoplay fields are deprecated because videoBg is a still-frame background, not video playback.

1await painter.createCanvas({2  width: 1920,3  height: 1080,4  videoBg: {5    source: './clip.mp4',6    time: 1.0,7    fit: 'cover',8    align: 'center',9    filters: [{ type: 'contrast', value: 12 }],10    format: 'jpg',11    quality: 2,12  },13});

#After the primary fill

You can still add bgLayers, patternBg, noiseBg on top — see the following pages.