@viewrium/sdk

Official JavaScript / TypeScript SDK for the Viewrium API. Create and manage 3D models, API keys, and usage records.

Install

npm install @viewrium/sdk
# or
pnpm add @viewrium/sdk
# or
yarn add @viewrium/sdk

Node 18+, Deno, Bun, browsers, and edge runtimes all supported (uses the global fetch).

Quickstart

import Viewrium from "@viewrium/sdk";

const viewrium = new Viewrium(process.env.VIEWRIUM_API_KEY!);

const model = await viewrium.models.create({
  customId: "sku-1",
  images: ["https://example.com/img1.jpg", "https://example.com/img2.jpg"],
  height: 90,
  tags: ["chair", "summer-2026"],
});

console.log(model.id, model.status);

const listing = await viewrium.models.list({ tag: "chair", limit: 20 });
for (const m of listing.data) {
  console.log(m.custom_id, m.status);
}

Configure

const viewrium = new Viewrium("sk_live_...", {
  apiBase: "https://api.viewrium.com",  // default
  timeoutMs: 60_000,                      // default
  maxRetries: 3,                          // retries 429 / 5xx, respects Retry-After
});

If you omit the first argument, the SDK reads process.env.VIEWRIUM_API_KEY. Likewise process.env.VIEWRIUM_API_BASE overrides the default base URL.

Resources

| Resource | Methods | |---|---| | viewrium.models | create, createFromImages, createFromVideo, retrieve, list, modify, delete, listEvents | | viewrium.apiKeys | create, list, delete | | viewrium.usage | retrieve | | viewrium.tags | list |

Uploading files

createFromImages and createFromVideo accept Blob, File, or (in Node) a filesystem path string.

import { readFile } from "node:fs/promises";

// Node: filesystem path (easiest)
const model = await viewrium.models.createFromImages(
  ["./chair-front.jpg", "./chair-side.jpg", "./chair-back.jpg"],
  { customId: "sku-1", height: 90, tags: ["chair"] },
);

// Anywhere: Blob/File (from a browser `<input type=file>` or `fetch` response)
const response = await fetch("https://example.com/chair.mp4");
const blob = await response.blob();
const model2 = await viewrium.models.createFromVideo(blob, {
  customId: "sku-2",
  height: 92,
});

Sizing

Pass height plus optional sizeUnit ("cm" or "in", default "cm"). The server normalizes to cm before storing. Explicit height wins over scraped values; if neither is present, the model renders unscaled.

await viewrium.models.create({
  images: [...],
  height: 35,
  sizeUnit: "in",   // stored as 88.9 cm
});

Errors

import {
  ViewriumError,      // base class
  AuthError,          // 401 or missing key
  NotFoundError,      // 404
  ValidationError,    // 400 / 409 / 422
  RateLimitError,     // 429 (has .retryAfter)
  APIError,           // 5xx / other
} from "@viewrium/sdk";

try {
  await viewrium.models.retrieve("not-a-real-id");
} catch (err) {
  if (err instanceof NotFoundError) {
    // ...
  } else if (err instanceof RateLimitError) {
    console.log("retry after", err.retryAfter, "seconds");
  } else {
    throw err;
  }
}

All ViewriumError subclasses carry .statusCode and .responseBody.

Retries

Requests retry automatically on 429 and 5xx responses up to maxRetries times, using Retry-After when the server provides it and exponential backoff otherwise. Network errors also retry.

TypeScript

Full types ship with the package. All response shapes (Model, ApiKey, UsageSummary, TagSummary, ...) and request params (ModelCreateParams, ModelUpdateParams, ...) are exported.

Custom fetch

For testing or custom transports, pass your own fetch:

const viewrium = new Viewrium("sk_live_...", {
  fetch: async (url, init) => {
    // intercept, log, proxy, etc.
    return globalThis.fetch(url, init);
  },
});

License

Apache 2.0.