POST /sequence
Generates a sequence of images for rotation and/or animation playback.
Request Body
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | Yes | - | URL or base64 data of the GLB model. |
frameCount | number | No | 8 | Number of frames to generate (min 1, max 32 for the Cloud API). |
rotationAxis | string | No | null | The axis to rotate around. Options: x (Pitch), y (Yaw), or z (Roll). Case-insensitive. If null or omitted, no rotation is applied. |
cameraOrbitSwingX | number | No | 0 | Swing range (0-120) applied to cameraOrbitX. Oscillates ±swing/2 around the base value over the sequence. |
cameraOrbitSwingY | number | No | 0 | Swing range (0-120) applied to cameraOrbitY. Oscillates ±swing/2 around the base value over the sequence. Set to 100 to match the previous vertical swing (25°–125°). |
rotationOrbit | string | No | null | Rotates the camera orbit over the sequence. "x" spins cameraOrbitX 0–360°, "y" spins cameraOrbitY 0–360°. |
updateFraming | boolean | No | false | When true, calls updateFraming() between frames to recalc camera framing after orientation/scale changes. |
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 | 0 | Rotation around the Y-axis (turning left/right). |
cameraOrbitX | number | No | 0 | Base camera azimuth (theta) in degrees. |
cameraOrbitY | number | No | 75 | Base camera elevation (phi) in degrees. |
cameraDistance | number | No | 105 | Camera distance as a percentage of tight framing (e.g., 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 play during the sequence. If set to "auto", the first available animation is used. If not provided or null, no animation is played and startTime/endTime are ignored. |
startTime | number | No | 0 (if animation) | The start time of the animation sequence in seconds. Only used if animationName is provided. Defaults to 0 if not specified. |
endTime | number | No | animation duration (if animation) | The end time of the animation sequence in seconds. Only used if animationName is provided. If not specified, uses the full animation duration. |
outputFormat | string | No | "webp" | The desired image format of all frames. 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. |
images | array | An array of objects, where each object contains the index number and the base64-encoded image data URL. |
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). |