Interface: ApiImageConfigSettings
Configuration settings for image generation.
This interface controls how product images are generated in different contexts throughout the configurator. It specifies image format, size, background color, and camera positioning to ensure consistent, high-quality visualizations.
These settings can be customized for different use cases like thumbnails, detail views, and AR previews to optimize both quality and performance.
Properties
backgroundColor?
optionalbackgroundColor:string
Background color for the image.
For JPEG images, this color fills the background. For PNG images with transparency, this may affect edge anti-aliasing.
Must be a valid hex color code (e.g., '#FFFFFF' for white).
customCameraPosition?
optionalcustomCameraPosition:string
Specific camera position for image capture.
This JSON string defines a precise camera position (coordinates, angles, and target) to use when capturing the image. This is useful for ensuring consistent product views from standard angles.
Example: {"position":{"x":-1.5,"y":1.7,"z":-5.2},"target":{"x":0,"y":0.6,"z":0},"radius":5.5}
customCanvasSize?
optionalcustomCanvasSize:Partial<Dimensions>
Custom dimensions to override default canvas sizing.
When provided, these dimensions override the default aspect ratio and calculated height. This may affect how the product appears within the frame.
Use with caution as it may cause the product to appear partially out of frame unless combined with withAutozoom.
extension?
optionalextension:"png"|"jpeg"|"jpg"
File format for generated images.
Determines the image format and associated MIME type:
- 'png': Lossless format with transparency support
- 'jpeg'/'jpg': Compressed format without transparency
PNG is ideal for images that need transparency or highest quality, while JPEG is better for smaller file sizes and faster loading.
size?
optionalsize:number
Width of the generated image in pixels.
The height will be automatically calculated based on the canvas aspect ratio. Larger sizes produce higher quality images but require more processing time and bandwidth.
Note: On iOS devices, sizes larger than 2048px may cause performance issues. For e-commerce use, 1000-1200px is typically recommended.
withAutozoom?
optionalwithAutozoom:boolean
Automatically adjusts zoom to ensure the product fits the canvas.
When true, the camera will automatically zoom out to ensure the entire product is visible within the image, regardless of the current view or canvas dimensions.
This is particularly useful with customCanvasSize to prevent cropping.
withCameraReset?
optionalwithCameraReset:boolean
Resets the camera to a standard position before capturing.
When true, the camera returns to either the initial position defined by the scene/product or the position specified by customCameraPosition before taking the screenshot.
This ensures consistent product views regardless of the current user-controlled camera position.