JavaScript SDK
Install and use @viewrium/sdk, the official typed TypeScript client for the /v1 API.
@viewrium/sdk is the official JavaScript/TypeScript SDK - an ergonomic, fully typed client for the
Viewrium /v1 API. It ships ESM and CommonJS builds with self-contained type declarations, and runs
anywhere there is a fetch (Node 18+, Bun, Deno, edge runtimes, the browser).
Install
npm install @viewrium/sdkClient
import { Viewrium } from "@viewrium/sdk";
const client = new Viewrium({ apiKey: "sk_live_..." });Options:
const client = new Viewrium({
apiKey: "sk_live_...",
baseUrl: "https://api.viewrium.com", // default; trailing slash stripped
fetch: customFetch, // optional; defaults to globalThis.fetch
});There is also a createViewrium({ apiKey }) factory that is equivalent to new Viewrium(...).
Use a secret (
sk_) key only on a server. For browser viewers, use the<viewrium-viewer>embed with a publishable (pk_) key instead of the SDK.
Resources
| Resource | Methods |
|---|---|
client.products | create, list, retrieve, retrieveByCustomId, update, delete, batchDelete, publish, tags, review, updateImage, updateModel, rescale, createTicket, order, export, qr |
client.apiKeys | list, create, revoke |
client.usage | get |
client.webhooks | list, create, retrieve, update, delete, listDeliveries |
client.beacon | send |
client | health() |
Request and response types (ProductCreateParams, Product, ProductCreateResult,
ProductParked, PlannedView, ModelPlan, ProductCost, UsageProductTotals, and so on) are
exported and derived directly from the API's OpenAPI schema. The painting types
are PaintingOptions, PaintingInspection, PaintingSettings, PaintingRebuild and
PaintingUpdate.
Every field of every response type is listed on its object page. The SDK exports short aliases for the schema's names; each object page shows both:
| SDK type | Schema | Fields |
|---|---|---|
Product, ProductSummary, ProductList, PublicProduct | ProductResponse, ... | The Product object |
ProductImage, ProductModel | ProductImageResponse, ProductModelResponse | The Product object |
PaintingSettings, PaintingRebuild | same | The Product object |
ProductParked, ProductOrderParked, PlannedView, ModelPlan, ProductCost, PaintingInspection | ProductParkedResponse, ... | The Quote object |
GateFlags | same | The Product object |
Ticket | TicketResponse | The Ticket object |
ProductBatchResult, ProductReviewResult, ProductExportQueued, Tags | ProductBatchResponse, ... | Product operation results |
ApiKeyList, ApiKeyCreated | ApiKeyListResponse, ApiKeyCreateResponse | The API key object |
WebhookEndpoint, WebhookEndpointList, WebhookEndpointCreated | WebhookEndpointResponse, ... | The Webhook endpoint object |
WebhookDeliveryList | WebhookDeliveryListResponse | The Webhook delivery object |
Usage, UsageProductTotals | UsageResponse, UsageProductTotals | The Usage object |
ViewriumError | ErrorEnvelope | The Error object |
products.create resolves to two shapes
create resolves to a ProductCreateResult - the parked quote for a fresh request, or the
committed product once you post the token back. Discriminate on status:
const result = await client.products.create({
image_urls: ["https://cdn.example.com/chair.jpg"],
draft: { title: "Oak dining chair" },
});
if (result.status === "parked") {
console.log(result.cost.total_credits, result.model.unseen_views);
const product = await client.products.create({ resume_token: result.resume_token });
if (product.status === "parked") throw new Error("a resume always commits");
console.log(product.id, product.display_status);
}See the quote and commit guide for the whole flow.
Listing and filtering
const page = await client.products.list({
scope: "org",
status: ["published"],
tag: ["chairs"],
tag_match: "all",
q: "oak",
custom_id: "sku-123",
limit: 50,
offset: 0,
sort: "created_at",
order: "desc",
});
for (const product of page.data) {
console.log(product.id, product.title, product.display_status);
}products.tags and products.export take the same filters.
Analytics
usage.get takes an arbitrary window, not a preset. group_by: "product" additionally returns the
window's best-performing products, ranked by 3D views then AR entries and capped at 20, each with
its title.
const usage = await client.usage.get({
start: "2026-06-01T00:00:00Z",
end: "2026-09-01T00:00:00Z",
granularity: "day", // or "hour"
event_type: "view",
include_internal: false, // your own team's traffic is excluded by default
group_by: "product",
});
for (const row of usage.by_product ?? []) {
console.log(row.title, row.totals);
}The export archive
products.export resolves to the ZIP of finished images as a Blob - or, when more images need
finishing than one request can do, to the queued answer (status: "queued"): they are finished in
the background, a download link is emailed, and the same call resolves to the archive once they
are done.
const archive = await client.products.export({ tag: ["chairs"] });
if (archive instanceof Blob) {
// write it out
} else {
console.log(`finishing ${archive.to_finish} images; a link goes to ${archive.notify_email}`);
}QR codes
products.qr resolves to the product's QR code as PNG bytes (a Uint8Array): the minimal
layout by default, the card with the steps with guide: true, size from 256 to 2048 px
(default 1024). See QR codes.
import { writeFile } from "node:fs/promises";
await writeFile("chair-qr.png", await client.products.qr(productId, { guide: true, size: 2048 }));Errors
Non-2xx responses throw a typed ViewriumError subclass. Branch with instanceof:
import {
Viewrium,
ViewriumError,
AuthenticationError,
ConflictError,
RateLimitError,
ConnectionError,
} from "@viewrium/sdk";
const client = new Viewrium({ apiKey: "sk_live_..." });
try {
await client.products.create({ image_urls: ["https://cdn/chair.jpg"] });
} catch (err) {
if (err instanceof AuthenticationError) {
// 401
} else if (err instanceof ConflictError) {
// 409, e.g. duplicate custom_id
} else if (err instanceof RateLimitError) {
// 429 - back off and retry
} else if (err instanceof ConnectionError) {
// never reached the API
} else if (err instanceof ViewriumError) {
console.log(err.status, err.code, err.message, err.details);
}
}The full status-to-error table is on the Authentication page.
Full example
import { Viewrium } from "@viewrium/sdk";
const client = new Viewrium({ apiKey: "sk_live_..." });
const quote = await client.products.create({
image_urls: ["https://cdn.example.com/chair.jpg"],
draft: { title: "Oak dining chair", custom_id: "sku-oak-chair", dimensions: { height: 92 } },
});
if (quote.status !== "parked") throw new Error("unexpected: already committed");
const committed = await client.products.create({ resume_token: quote.resume_token });
if (committed.status === "parked") throw new Error("a resume always commits");
let product = await client.products.retrieve(committed.id);
while (product.display_status === "generating") {
await new Promise((r) => setTimeout(r, 5000));
product = await client.products.retrieve(product.id);
}
console.log(product.display_status, product.model?.status);
await client.products.update(product.id, { published: true });