Quickstart
Get an API key and create your first product with the Viewrium SDK in a few minutes.
This guide takes you from zero to a finished GLB: create a key, install an SDK, quote a product from a couple of images, commit it, and read back the model's URL.
1. Get an API key
Create a secret key (sk_) in the Viewrium dashboard under Settings -> Advanced -> API
keys. Secret keys are shown once, so copy it somewhere safe. Keep it server-side and never ship
it to a browser.
Every request authenticates with Authorization: Bearer <key>; the SDKs add this header for you.
2. Install an SDK
pip install viewriumnpm install @viewrium/sdk3. Ask for a quote
products.create is the one entrypoint. Supply exactly one source - here, a list of image
URLs. Viewrium hosts nothing for you: pass publicly reachable URLs to your assets.
A fresh request parks. Nothing is written, no product exists yet: you get back the plan (which
page positions will be produced), the model verdict, the price, and a resume_token.
from viewrium import ProductCreateRequest, ProductDraft, Viewrium
client = Viewrium("sk_live_...")
parked = client.products.create(
ProductCreateRequest(
image_urls=[
"https://cdn.example.com/chair-front.jpg",
"https://cdn.example.com/chair-side.jpg",
],
draft=ProductDraft(title="Oak dining chair"),
)
)
print(parked.cost.total_credits) # what committing will cost
print(len(parked.plan)) # the page positions it will produce
print(parked.model.allowed) # whether a 3D model is on the tableimport { Viewrium } from "@viewrium/sdk";
const client = new Viewrium({ apiKey: "sk_live_..." });
const parked = await client.products.create({
image_urls: [
"https://cdn.example.com/chair-front.jpg",
"https://cdn.example.com/chair-side.jpg",
],
draft: { title: "Oak dining chair" },
});
if (parked.status !== "parked") throw new Error("unexpected: already committed");
console.log(parked.cost.total_credits, parked.plan?.length, parked.model.allowed);4. Commit it
Post the token back. That is the only call that writes anything, and it starts the run.
from viewrium import ProductParked
product = client.products.create(
ProductCreateRequest(resume_token=parked.resume_token)
)
assert not isinstance(product, ProductParked) # a resume always commits
print(product.id, product.display_status) # -> "<uuid>", "generating"const product = await client.products.create({ resume_token: parked.resume_token });
if (product.status === "parked") throw new Error("a resume always commits");
console.log(product.id, product.display_status); // -> "<uuid>", "generating"You may still edit the draft on the resume - the title, price, tags and dimensions are yours to
change right up to the commit. What you may not change is the order or the overrides: the plan
you were quoted for is immutable, and changing what gets generated means a new request.
5. Wait for the result
Poll products.retrieve until display_status leaves generating. The model's GLB is on
product.model.glb_url; the catalog images are product.images.
import time
while True:
product = client.products.retrieve(product.id)
if product.display_status != "generating":
break
time.sleep(5)
if product.model and product.model.glb_url:
print("GLB:", product.model.glb_url)
for image in product.images:
print(image.view, image.status, image.baked_url)let current = await client.products.retrieve(product.id);
while (current.display_status === "generating") {
await new Promise((r) => setTimeout(r, 5000));
current = await client.products.retrieve(current.id);
}
console.log("GLB:", current.model?.glb_url);For production, prefer webhooks over polling - Viewrium calls your endpoint the moment a run finishes.
6. Publish and show it
A product is not public until you publish it. Set published on the product, then embed the viewer
on any page with the <viewrium-model> web component and a publishable (pk_) key.
from viewrium import ProductUpdateRequest
client.products.update(product.id, ProductUpdateRequest(published=True))await client.products.update(product.id, { published: true });Next steps
- How generation works - the park/commit gate, every source type, and the model verdict.
- Guides - generate from video, a product URL, or an existing model.
- SDK reference - every resource and method.