POST /single
Generates a single image of the model from a specific angle, with adjustable rendering options.
Request Body
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | Yes | - | URL or base64 data of the GLB model. |
width | number | No | 1024 | Output image width (64-2048). |
height | number | No | 1024 | Output image height (64-2048). |
roll | number | No | 0 | Rotation around the Z-axis (tilting sideways). |
pitch | number | No | 0 | Rotation around the X-axis (tilting forward/backward). |
yaw | number | No | 315 | Rotation around the Y-axis (turning left/right). |
cameraOrbitX | number | No | 0 | Base camera azimuth (theta) in degrees for positioning the camera around the model. |
cameraOrbitY | number | No | 75 | Base camera elevation (phi) in degrees. |
cameraDistance | number | No | 105 | Camera distance as a percentage of tight framing (105 → 105%). Increase to pull the camera back (wider view); decrease to move it closer (tighter framing). |
scaleX | number | No | 1 | Model scale factor for the X-axis. |
scaleY | number | No | 1 | Model scale factor for the Y-axis. |
scaleZ | number | No | 1 | Model scale factor for the Z-axis. |
shadowIntensity | number | No | 0 | Controls the opacity of the model's shadow. A value of 0 makes the shadow invisible, and 1 makes it fully opaque. |
shadowSoftness | number | No | 1 | Controls the blurriness of the shadow, clamped between 0 (hard) and 1 (soft). Softer shadows render faster. |
background | string | No | "transparent" | Sets the visual background (does not affect scene lighting). Accepts a URL, base64 data, and CSS color formats like hex (#RRGGBB), rgba, the keyword transparent, or CSS gradients with hex color stops (e.g., "radial-gradient(circle, #f2f2f2 0%, #2b2b2b 150%)"). For background colors that affect lighting, use environment or skybox with a CSS color or gradient string. |
environment | string | No | null | Specifies the environmental image used for reflections and lighting. Accepts a URL, base64 data, CSS color/gradient, or a special value. Supported image formats include PNG, HDR, and UltraHDR JPEG. CSS gradients must use hex color stops (e.g., "linear-gradient(to right, #ffffff, #00abff)"). Special values: "neutral" (default lighting), "legacy" (old default environment). |
skybox | string | No | null | Specifies the background image and environment lighting of the scene. Accepts a URL, base64 data, or a CSS color/gradient string. Supported image formats include PNG, HDR, and UltraHDR JPEG. CSS gradients must use hex color stops (e.g., "linear-gradient(to right, #ffffff, #00abff)"). HDR images are recommended for realistic lighting. UltraHDR JPEG is recommended for efficient HDR compression (see this online converter). |
skyboxHeight | string | No | "0m" | Sets the height of the skybox, relative to the model. Accepts units "m", "cm", "mm", or a number interpreted as meters. For example, "1.5m". |
exposure | number | No | 1.0 | Adjusts the overall brightness of the scene. Higher values increase brightness. |
toneMapping | string | No | "neutral" | The tone mapping algorithm to use. neutral is best for color accuracy. aces provides a more cinematic, film-like look but can alter hues. agx is a newer alternative to aces. |
variantName | string | No | null | The name of a material variant defined in the GLB file. Set to null to use the default material. |
includeMetadata | boolean | No | false | If true, the response will include a metadata object with details about the 3D model. |
animationName | string | No | null | The name of the animation to display. If not specified but currentTime is provided, uses the first available animation. |
currentTime | number | No | null | The time position within the animation in seconds. If not specified but animationName is provided, defaults to 0 (start of animation). |
outputFormat | string | No | "webp" | The desired image format. Supported values are webp, png, and avif. |
quality | number | No | 70 | The compression quality for lossy formats like webp and avif, ranging from 1 to 100. Higher values mean better quality and larger file sizes. |
Response
A successful request returns a JSON object with the following fields:
| Field | Type | Description |
|---|---|---|
success | boolean | Always true for a successful response. |
image | string | A base64-encoded data URL of the rendered image. |
metadata | object | An object containing details about the model. This field is only present if includeMetadata was set to true. |
warnings | array | Optional messages when a non-critical issue occurred (for example, an environment/skybox image failed to load and the render proceeded without it). |