Viewrium Docs
SDKs

Python SDK

Install and use viewrium, the official typed Python client for the /v1 API.

viewrium is the official Python SDK - a synchronous, typed client for the Viewrium /v1 API, published on PyPI.

Install

pip install viewrium

Or with uv:

uv add viewrium

Client

from viewrium import Viewrium

client = Viewrium("sk_live_...")            # positional api_key

Options:

client = Viewrium(
    "sk_live_...",
    base_url="https://api.viewrium.com",    # default
    timeout=30.0,                            # seconds
)

The client is also a context manager, which closes the underlying HTTP connection for you:

with Viewrium("sk_live_...") as client:
    page = client.products.list()

Request models

Write operations take typed pydantic request objects, importable from the top-level package:

from viewrium import (
    ProductCreateRequest,
    ProductDraft,
    ProductOrder,
    ProductOverrides,
    ProductUpdateRequest,
    ProductPublishRequest,
    ProductRescaleRequest,
    ProductOrderRequest,
    ProductReviewRequest,
    ProductImagePatch,
    ProductModelPatch,
    ProductFilters,
    ModelDimensions,
    PaintingOptions,        # draft.painting - see /docs/paintings
    PaintingUpdate,         # ProductUpdateRequest.painting
    ApiKeyCreateRequest,
    WebhookEndpointCreateRequest,
    WebhookEndpointUpdateRequest,
    BeaconRequest,
)

Only the fields you actually set are sent. That matters twice: an explicit None on an image patch clears an override where an omitted field leaves it alone, and a resume that never mentions order does not restate the order the quote was priced for.

Enums are exported too: ProductStatus, DisplayStatus, AssetStatus, ReviewStatus, WarningKind, ListScope, TagMatch, ProductSortField, SortOrder, SourceType, KeyType, BeaconEventType, UsageEventType, WebhookEventType, DimensionUnit, WidthAxis, PaintingEdge, PaintingDimensionsOf, PaintingRebuildStatus.

Every field of every response model is listed on its object page. The models mirror the API's schema field for field (a test fails the SDK's build when they drift); a few carry shorter names than the schema's, and each object page shows both:

ModelSchemaFields
Product, ProductSummary, ProductListResponse, PublicProductProductResponse, ...The Product object
ProductImage, ProductModel, ProductSource, ProductWarningProductImageResponse, ...The Product object
PaintingSettings, PaintingRebuildsameThe Product object
ProductParked, ProductOrderParked, PlannedView, ModelPlan, ProductCost, PaintingInspectionProductParkedResponse, ...The Quote object
GateFlags, GateReasonsameThe Product object
TicketTicketResponseThe Ticket object
ProductBatchResponse, ProductReviewResponse, ProductExportQueued, TagsResponse...Product operation results
ApiKey, ApiKeyCreateResponse, ApiKeyListResponseApiKeyResponse, ...The API key object
WebhookEndpoint, WebhookEndpointCreateResponse, WebhookEndpointListResponseWebhookEndpointResponse, ...The Webhook endpoint object
WebhookDelivery, WebhookDeliveryListResponseWebhookDeliveryResponse, ...The Webhook delivery object
UsageResponse, UsageBucket, UsageProductTotalssameThe Usage object
ViewriumErrorErrorEnvelopeThe Error object

Resources

ResourceMethods
client.productscreate, list, retrieve, retrieve_by_custom_id, update, delete, batch_delete, publish, tags, review, update_image, update_model, rescale, create_ticket, order, export, qr
client.api_keyslist, create, revoke
client.usageget
client.webhookslist, create, retrieve, update, delete, list_deliveries
client.beaconsend
clienthealth()

products.create returns two types

create returns a ProductParked for a fresh request - the quote, with nothing written - or a Product once you commit the token:

from viewrium import ProductCreateRequest, ProductParked

result = client.products.create(ProductCreateRequest(image_urls=["https://cdn/chair.jpg"]))

if isinstance(result, ProductParked):
    print(result.cost.total_credits, result.model.unseen_views)
    result = client.products.create(ProductCreateRequest(resume_token=result.resume_token))

print(result.id, result.display_status)

See the quote and commit guide for the whole flow.

Listing and filtering

The catalog's filters are one ProductFilters object, shared by list, tags and export exactly as the API shares them. Paging and sorting are keyword arguments on list.

from viewrium import DisplayStatus, ListScope, ProductFilters, ProductSortField, SortOrder

page = client.products.list(
    ProductFilters(
        scope=ListScope.ORG,
        status=[DisplayStatus.PUBLISHED],
        tag=["chairs"],
        q="oak",
        custom_id="sku-123",
    ),
    limit=50,
    offset=0,
    sort=ProductSortField.CREATED_AT,
    order=SortOrder.DESC,
)
for product in page.data:
    print(product.id, product.title, product.display_status)
print(page.total)

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.

from datetime import UTC, datetime, timedelta

from viewrium import UsageEventType

end = datetime.now(UTC)
usage = client.usage.get(
    start=end - timedelta(days=90),
    end=end,
    granularity="day",            # or "hour"
    event_type=UsageEventType.VIEW,
    include_internal=False,       # your own team's traffic is excluded by default
    group_by="product",
)

for row in usage.by_product:
    print(row.title, row.totals)

The export archive

products.export returns the ZIP of finished images as bytes - or, when more images need finishing than one request can do, a ProductExportQueued: they are finished in the background, a download link is emailed, and the same call returns the archive once they are done.

from viewrium import ProductExportQueued, ProductFilters

archive = client.products.export(ProductFilters(tag=["chairs"]))
if isinstance(archive, ProductExportQueued):
    print("finishing", archive.to_finish, "images; a link goes to", archive.notify_email)
else:
    open("catalog.zip", "wb").write(archive)

QR codes

products.qr returns the product's QR code as PNG bytes: the minimal layout by default, the card with the steps with guide=True, size from 256 to 2048 px (default 1024). See QR codes.

from pathlib import Path

Path("chair-qr.png").write_bytes(client.products.qr(product_id, guide=True, size=2048))

Errors

Non-2xx responses raise a ViewriumError subclass. Catch the specific type you care about:

from viewrium import (
    Viewrium,
    ViewriumError,
    AuthenticationError,
    ConflictError,
    RateLimitError,
    APIConnectionError,
)

client = Viewrium("sk_live_...")
try:
    client.products.create(ProductCreateRequest(image_urls=["https://cdn/chair.jpg"]))
except AuthenticationError:
    ...        # 401
except ConflictError as err:
    ...        # 409, e.g. duplicate custom_id
except RateLimitError:
    ...        # 429 - back off and retry
except APIConnectionError:
    ...        # never reached the API
except ViewriumError as err:
    print(err.status, err.code, err.message, err.details)

The full status-to-exception table is on the Authentication page.

Full example

import time

from viewrium import (
    ModelDimensions,
    ProductCreateRequest,
    ProductDraft,
    ProductParked,
    ProductUpdateRequest,
    Viewrium,
)

with Viewrium("sk_live_...") as client:
    result = client.products.create(
        ProductCreateRequest(
            image_urls=["https://cdn.example.com/chair.jpg"],
            draft=ProductDraft(
                title="Oak dining chair",
                custom_id="sku-oak-chair",
                dimensions=ModelDimensions(height=92),
            ),
        )
    )

    if isinstance(result, ProductParked):
        print("costs", result.cost.total_credits, "credits")
        result = client.products.create(
            ProductCreateRequest(resume_token=result.resume_token)
        )
    assert not isinstance(result, ProductParked)

    product = result
    while product.display_status == "generating":
        time.sleep(5)
        product = client.products.retrieve(product.id)

    print(product.display_status, product.model.status if product.model else None)
    client.products.update(product.id, ProductUpdateRequest(published=True))

On this page