The Product object

Every field of a product - its images, its 3D model, its sources and warnings - and the public projection a publishable key reads.

A product is what products.create commits and products.retrieve answers. A session or a secret key reads the full ProductResponse; a publishable key reads the allow-listed PublicProductResponse, and only for a published product with a ready model. The catalog list answers ProductSummary rows, which carry no nested assets.

ProductResponse

JavaScript: Product · Python: viewrium.Product

A product with its assets. status is its review status; display_status is what to show. images are in page order; warnings lists every warning, image warnings first.

iduuidrequired

Unique identifier.

org_iduuidrequired

The organization it belongs to.

titlestringrequired

The product's title.

custom_idstringoptionalnullable

Your own id for the product, unique within the organization.

tagsstring[]optional

Your tags.

statusProductStatusrequired

The stored review status: awaiting_review, needs_attention, ready_to_publish or complete.

One of "awaiting_review", "needs_attention", "ready_to_publish", "complete"

display_statusDisplayStatusrequired

The status to show: the stored status, except generating while any asset is in flight, failed when nothing usable was produced, and published once it is live.

One of "published", "generating", "failed", "awaiting_review", "needs_attention", "ready_to_publish", "complete"

publishedbooleanoptional

Whether the product is live (the embed and the hosted viewer serve it).

Default false

formstringoptionalnullable

The product's shape class from the analysis: regular (most furniture), wall (hung or mounted on a wall), cylindrical (near rotationally symmetric), character (has a face or front, e.g. a figure) or painting.

source_typeSourceTypeoptionalnullable

How it was created: image, video, url (a product page) or model (a finished 3D file).

One of "image", "video", "url", "model", "scan", "upload"

pricenumberoptionalnullable

Your price.

currencystringoptionalnullable

Your price's currency.

heightnumberoptionalnullable

The product's height in cm.

widthnumberoptionalnullable

The product's width in cm.

depthnumberoptionalnullable

The product's depth in cm.

display_unitDimensionUnitoptionalnullable

The unit the dimensions are shown in. They are always stored and returned in cm.

One of "mm", "cm", "m", "in", "ft"

images_orderedbooleanoptional

Whether the catalog images were ordered.

Default false

thumbnail_urlstringoptionalnullable

The card image: the first ready image in page order, else the model's poster.

has_warningsbooleanoptional

Whether the product has any warning.

Default false

warning_countintegeroptional

How many warnings the product has.

Default 0

comment_countintegeroptional

How many comments the product has.

Default 0

image_countintegeroptional

How many deliverable images are ready.

Default 0

model_statusAssetStatusoptionalnullable

The 3D model's status. Null when no model was ordered.

One of "planned", "generating", "ready", "failed", "skipped"

ownerProductOwneroptionalnullable

Who created the product.

created_atdatetimerequired

When it was created.

updated_atdatetimeoptionalnullable

When it was last changed.

viewer_urlstringoptionalnullable

The product's hosted viewer page, which its QR code encodes. It opens only while the product is published.

descriptionstringoptionalnullable

The product's description.

wall_mountedbooleanoptional

Whether the product hangs on a wall (AR places it on a wall).

Default false

product_typestringoptionalnullable

What the object is in a few words, as a shopper would search for it (from the analysis).

material_wordsstringoptionalnullable

The dominant material and finish in a few words (from the analysis).

transparentbooleanoptional

The analysis found a see-through part.

Default false

metadatamap of string to anyoptional

Your free-form key/value data.

sourcesProductSourceResponse[]optional

The photographs or video the product was made from, in order.

imagesProductImageResponse[]optional

The catalog images, in page order.

modelProductModelResponseoptionalnullable

The 3D model. Null when none was ordered.

warningsProductWarning[]optional

Every warning for the product, image warnings first.

open_request_countintegeroptional

How many change requests are open on the product.

Default 0

paintingPaintingSettingsoptionalnullable

A painting's settings. Form painting only.

viewer_desktopViewerDesktopModeoptional

How the embed shows the product on a desktop: viewer, qr, button or hidden.

One of "viewer", "qr", "button", "hidden"

Default "viewer"

viewer_mobileViewerMobileModeoptional

How the embed shows the product on a phone: viewer, button or hidden.

One of "viewer", "button", "hidden"

Default "viewer"

ProductOwner

JavaScript: no alias - an element of the type that holds it · Python: viewrium.ProductOwner

Who created the product.

iduuidrequired

The creator's profile id.

display_namestringoptionalnullable

The creator's display name.

emailstringrequired

The creator's email.

ProductSourceResponse

JavaScript: no alias - an element of the type that holds it · Python: viewrium.ProductSource

iduuidrequired

Unique identifier.

kindstringrequired

photo or video.

One of "photo", "video"

urlstringrequired

Public URL of the stored source file.

original_namestringoptionalnullable

The uploaded file's name, when known.

positionintegeroptional

The source's 0-based order within the product.

Default 0

azimuthstringoptionalnullable

Camera bearing around the product, in 45-degree steps: front, front-right, right, back-right, back, back-left, left, front-left.

tiltstringoptionalnullable

Camera elevation: level sees the sides only, above sees the sides and the top, overhead sees only the top.

cleanbooleanoptionalnullable

True when the product is alone, whole and unobstructed in the photograph - good enough to ship as it is. Null when not assessed.

created_atdatetimerequired

When it was created.

ProductImageResponse

JavaScript: ProductImage · Python: viewrium.ProductImage

One catalog image position. A position that was not produced reads status: skipped with a skip_reason and has no files.

iduuidrequired

Unique identifier.

viewstringrequired

The page position, e.g. front, side, back, angle, front-elevated, detail. An extra standing in for a position carries a suffix such as side-2.

kindstringrequired

wanted: a catalog position the product was planned for. extra: an additional viewpoint used to fill an empty position.

One of "wanted", "extra"

stands_forstringrequired

The catalog position this image fills: view itself for a wanted image, the position an extra substitutes for.

statusAssetStatusrequired

planned, generating, ready, failed, or skipped (a withheld position, which has no files).

One of "planned", "generating", "ready", "failed", "skipped"

skip_reasonstringoptionalnullable

Why the position was not produced, in plain words. Set when status is skipped.

routestringoptionalnullable

How the image is made: reuse ships the photograph as it is, edit edits a photograph, generate creates the view from reference photos. Null for a skipped position.

One of "reuse", "edit", "generate"

sourcestringoptionalnullable

What produced the image: photograph (yours, reused), edited (yours, edited) or generated.

One of "photograph", "edited", "generated"

evidencestringoptionalnullable

How well the photographs cover this view: seen (a clean photo shows it), pinned (a photo shows it but is not clean, or photos on both sides bracket it), implied (a rotationally symmetric product's far side), unseen (nothing shows it).

azimuthstringoptionalnullable

Camera bearing around the product, in 45-degree steps: front, front-right, right, back-right, back, back-left, left, front-left.

tiltstringoptionalnullable

Camera elevation: level sees the sides only, above sees the sides and the top, overhead sees only the top.

source_photo_iduuidoptionalnullable

The source photograph this image reuses, edits or is anchored on.

attemptsintegeroptional

How many generation attempts were made.

Default 0

flaggedbooleanoptional

True when the view could not be confirmed against the photographs (a view generated with unseen evidence).

Default false

cut_flaggedbooleanoptional

True when the background-removal check judged the cut-out possibly wrong.

Default false

cut_problemsstringoptionalnullable

The cut-out checker's description of what looks wrong. Null when nothing was flagged.

review_statusReviewStatusoptional

Your decision: pending, accepted or rejected. Once decided it never returns to pending.

One of "pending", "accepted", "rejected"

Default "pending"

filenamestringrequired

The download filename: filename_override when set, else a generated SEO name.

alt_textstringrequired

The image's alt text: alt_override when set, else generated.

filename_overridestringoptionalnullable

Your filename, when you set one.

alt_overridestringoptionalnullable

Your alt text, when you set one.

shadow_overrideShadowOverrideoptionalnullable

Your shadow settings for this image, merged field by field over the calibrated defaults.

background_overrideinteger[3]optionalnullable

Your backdrop colour for this image, [r, g, b].

frame_scalenumberoptionalnullable

The shared scale that makes the product fill the frame at the same size across the set's images.

contact_regionsnumber[][]optional

Where the product touches the ground, as [ymin, xmin, ymax, xmax] boxes on a 0-1000 scale. Drives the contact shadow; empty for wall pieces.

raw_urlstringoptionalnullable

URL of the uncut image. Null for a skipped position.

cutout_urlstringoptionalnullable

URL of the background-removed (transparent) image. Null for a skipped position and for detail.

warningsProductWarning[]optional

This image's warnings.

created_atdatetimerequired

When it was created.

updated_atdatetimeoptionalnullable

When it was last changed.

ProductModelResponse

JavaScript: ProductModel · Python: viewrium.ProductModel

The product's 3D model. No response carries a URL for the model file: mint a single-use ticket with POST /v1/products/{id}/tickets.

iduuidrequired

Unique identifier.

statusAssetStatusrequired

planned, generating, ready or failed.

One of "planned", "generating", "ready", "failed", "skipped"

review_statusReviewStatusoptional

Your decision: pending, accepted or rejected.

One of "pending", "accepted", "rejected"

Default "pending"

thumbnail_urlstringoptionalnullable

URL of the model's poster image. The model file itself has no URL: mint a ticket.

scale_factornumberoptionalnullable

The multiplier applied to the geometry to match the product's real dimensions.

width_axisstringoptionalnullable

Which of the model's horizontal axes is its width (x or z); the other is its depth.

One of "x", "z"

flagsGateFlagsoptional

The analysis's structured read of the product: the risks it found and why.

warningsProductWarning[]optional

The model's warnings.

created_atdatetimerequired

When it was created.

completed_atdatetimeoptionalnullable

When the model finished. Null while it is in progress.

ProductWarning

JavaScript: no alias - an element of the type that holds it · Python: viewrium.ProductWarning

A warning about a product or one of its images.

kindWarningKindrequired

cut, generation, missing, lighting, model_failed or model_risk.

One of "cut", "generation", "missing", "lighting", "model_failed", "model_risk"

scopestringrequired

image or product.

One of "image", "product"

titlestringrequired

A short headline.

detailstringrequired

The explanation. For cut, the cut-out checker's own words.

viewstringoptionalnullable

The affected position, for an image warning. Null otherwise.

PaintingSettings

JavaScript: PaintingSettings · Python: viewrium.PaintingSettings

A painting's settings, in cm: the ones the model being shown was built with. A rebuild in progress or failed is rebuild.

edgePaintingEdgerequired

How the painting's sides are finished: frame, solid (painted in edge_color) or stretch (the artwork's border pixels wrapped over the sides).

One of "frame", "solid", "stretch"

edge_colorstringrequired

The colour of a solid edge, as #RRGGBB.

dimensions_ofPaintingDimensionsOfrequired

Which rectangle the stated width x height describe: canvas or frame (the frame's outer edge).

One of "canvas", "frame"

canvas_width_cmnumberoptionalnullable

The canvas width in cm. Null while it is still to be derived from a size stated for the frame.

canvas_height_cmnumberoptionalnullable

The canvas height in cm. Null while it is still to be derived from a size stated for the frame.

depth_cmnumberoptionalnullable

The slab's depth in cm (a solid or stretch edge). Null for a framed painting.

has_framebooleanoptional

Whether the painting was ordered with a frame - the only way it ever has one.

Default false

rebuildPaintingRebuildoptionalnullable

An edit's rebuild in progress or failed. Null when there is none.

ShadowOverride

JavaScript: no alias - an element of the type that holds it · Python: viewrium.ShadowOverride

Your shadow settings for one image. Every field is optional: what you set replaces the calibrated default, and what you leave out keeps it.

modestringoptionalnullable

silhouette (cast shadow), contact (shadow at the ground contacts) or both.

One of "silhouette", "contact", "both"

toneinteger[3]optionalnullable

The shadow's colour, [r, g, b].

silhouetteShadowSilhouetteoptionalnullable

Cast-shadow settings.

contactShadowContactoptionalnullable

Contact-shadow settings.

groundShadowGroundoptionalnullable

Floor-line settings.

GateFlags

JavaScript: GateFlags · Python: viewrium.GateFlags

The risks the analysis found in the product. source_quality: poor is a warning only and never blocks anything.

transparentbooleanoptional

A part can be seen through (glass, acrylic).

Default false

geometry_riskbooleanoptional

Thin or fine shapes 3D reconstruction gets wrong (rods, wires, open weave, foliage, chains).

Default false

texture_riskbooleanoptional

Artwork, a logo, lettering or a pattern must land in the right place on the surface.

Default false

source_qualitystringoptional

poor when the photographs are weak (blurred, dim, small, hiding the item). It warns and never blocks.

One of "ok", "poor"

Default "ok"

reasonsGateReason[]optional

One sentence per raised flag.

PaintingRebuild

JavaScript: PaintingRebuild · Python: viewrium.PaintingRebuild

A painting edit's rebuild. The product keeps its delivered model, dimensions and settings while the rebuild runs and if it fails; one that succeeds replaces them and disappears.

statusPaintingRebuildStatusrequired

running or failed. A rebuild that succeeds replaces the settings and disappears.

One of "running", "failed"

requestedPaintingRequestedSettingsrequired

The settings the edit asked for, so a retry can re-send them.

requested_atdatetimeoptionalnullable

When the edit was made.

errorstringoptionalnullable

Why the rebuild failed. Set only when status is failed.

ShadowSilhouette

JavaScript: no alias - an element of the type that holds it · Python: viewrium.ShadowSilhouette

lengthnumberoptionalnullable

How far the cast shadow lies along the floor, as a fraction of the product's height.

leannumberoptionalnullable

Sideways drag away from the light, as a multiple of the lay-down distance.

blurNearnumberoptionalnullable

Blur in px where the shadow meets the product.

blurFarnumberoptionalnullable

Blur in px at the shadow's far end.

opacitynumberoptionalnullable

Shadow strength.

distanceFadenumberoptionalnullable

Alpha lost per unit of distance from the floor line (0-1).

ShadowContact

JavaScript: no alias - an element of the type that holds it · Python: viewrium.ShadowContact

trailPxnumberoptionalnullable

How far the contact shadow reaches out from the outline, in px.

darknumberoptionalnullable

Alpha at the outline (0-1).

endnumberoptionalnullable

Alpha at the far end (0-1).

midpointnumberoptionalnullable

Where the falloff crosses halfway (0.05-0.95).

regionHeightnumberoptionalnullable

Multiplier on each contact region's marked height.

ShadowGround

JavaScript: no alias - an element of the type that holds it · Python: viewrium.ShadowGround

nudgenumberoptionalnullable

Pixels to move the fitted floor line down.

tiltnumberoptionalnullable

Null fits the floor line to the contact regions; a number pins it.

GateReason

JavaScript: no alias - an element of the type that holds it · Python: viewrium.GateReason

One risk the analysis found, as a sentence about this item. Show it as it is.

codestringrequired

The flag raised: transparent, geometry_risk, texture_risk or source_quality.

sentencestringrequired

The analysis's sentence about this item. Show it as it is.

PaintingRequestedSettings

JavaScript: PaintingRequestedSettings · Python: viewrium.PaintingRequestedSettings

The settings a painting edit asked for, so a retry can re-send them.

edgePaintingEdgerequired

How the painting's sides are finished: frame, solid (painted in edge_color) or stretch (the artwork's border pixels wrapped over the sides).

One of "frame", "solid", "stretch"

edge_colorstringrequired

The colour of a solid edge, as #RRGGBB.

dimensions_ofPaintingDimensionsOfrequired

Which rectangle the stated width x height describe: canvas or frame (the frame's outer edge).

One of "canvas", "frame"

canvas_width_cmnumberoptionalnullable

The canvas width the edit asked for, in cm.

canvas_height_cmnumberoptionalnullable

The canvas height the edit asked for, in cm.

depth_cmnumberoptionalnullable

The slab depth the edit asked for, in cm.

frame_width_cmnumberoptionalnullable

The frame's outer width the edit gave, in cm. Null unless the edit was sized by the frame.

frame_height_cmnumberoptionalnullable

The frame's outer height the edit gave, in cm. Null unless the edit was sized by the frame.

PublicProductResponse

JavaScript: PublicProduct · Python: viewrium.PublicProduct

What a publishable key reads: only what a storefront needs. Served only for a published product with a ready model. The model file is reached through a ticket.

iduuidrequired

Unique identifier.

titlestringrequired

The product's title.

thumbnail_urlstringoptionalnullable

URL of the model's poster image.

model_statusAssetStatusoptionalnullable

The 3D model's status.

One of "planned", "generating", "ready", "failed", "skipped"

wall_mountedbooleanoptional

Whether the product hangs on a wall (AR places it on a wall).

Default false

paintingPaintingSettingsoptionalnullable

A painting's settings. Form painting only.

viewer_desktopViewerDesktopModeoptional

How the embed shows the product on a desktop: viewer, qr, button or hidden.

One of "viewer", "qr", "button", "hidden"

Default "viewer"

viewer_mobileViewerMobileModeoptional

How the embed shows the product on a phone: viewer, button or hidden.

One of "viewer", "button", "hidden"

Default "viewer"

ProductSummary

JavaScript: ProductSummary · Python: viewrium.ProductSummary

A product as the list returns it: its details and status, without nested assets.

iduuidrequired

Unique identifier.

org_iduuidrequired

The organization it belongs to.

titlestringrequired

The product's title.

custom_idstringoptionalnullable

Your own id for the product, unique within the organization.

tagsstring[]optional

Your tags.

statusProductStatusrequired

The stored review status: awaiting_review, needs_attention, ready_to_publish or complete.

One of "awaiting_review", "needs_attention", "ready_to_publish", "complete"

display_statusDisplayStatusrequired

The status to show: the stored status, except generating while any asset is in flight, failed when nothing usable was produced, and published once it is live.

One of "published", "generating", "failed", "awaiting_review", "needs_attention", "ready_to_publish", "complete"

publishedbooleanoptional

Whether the product is live (the embed and the hosted viewer serve it).

Default false

formstringoptionalnullable

source_typeSourceTypeoptionalnullable

How it was created: image, video, url (a product page) or model (a finished 3D file).

One of "image", "video", "url", "model", "scan", "upload"

pricenumberoptionalnullable

Your price.

currencystringoptionalnullable

Your price's currency.

heightnumberoptionalnullable

The product's height in cm.

widthnumberoptionalnullable

The product's width in cm.

depthnumberoptionalnullable

The product's depth in cm.

display_unitDimensionUnitoptionalnullable

The unit the dimensions are shown in. They are always stored and returned in cm.

One of "mm", "cm", "m", "in", "ft"

images_orderedbooleanoptional

Whether the catalog images were ordered.

Default false

thumbnail_urlstringoptionalnullable

The card image: the first ready image in page order, else the model's poster.

has_warningsbooleanoptional

Whether the product has any warning.

Default false

warning_countintegeroptional

How many warnings the product has.

Default 0

comment_countintegeroptional

How many comments the product has.

Default 0

image_countintegeroptional

How many deliverable images are ready.

Default 0

model_statusAssetStatusoptionalnullable

The 3D model's status. Null when no model was ordered.

One of "planned", "generating", "ready", "failed", "skipped"

ownerProductOwneroptionalnullable

Who created the product.

created_atdatetimerequired

When it was created.

updated_atdatetimeoptionalnullable

When it was last changed.

viewer_urlstringoptionalnullable

The product's hosted viewer page, which its QR code encodes. It opens only while the product is published.

ProductListResponse

JavaScript: ProductList · Python: viewrium.ProductListResponse

dataProductSummary[]required

This page of products.

totalintegerrequired

How many products match the filters.

limitintegerrequired

The page size the list was read with.

offsetintegerrequired

How many items were skipped before this page.

The Product object

On this page