@vizbl/node

Vizbl Node.js SDK

Official Node.js SDK for the Vizbl Developer API.

Installation

npm install @vizbl/node

Quick Start

import Vizbl from '@vizbl/node';

const vizbl = new Vizbl();

const result = await vizbl.objects.importModel({
  file: './chair.glb',
  name: 'Chair',
  wait: true,
});

console.log(result.tinuuid, result.url);

By default the SDK reads VIZBL_API_KEY from the environment and sends requests to https://api.vizbl.com.

Configuration

const vizbl = new Vizbl({
  apiKey: process.env.VIZBL_API_KEY,
  baseURL: 'https://api-dev.vizbl.com',
  timeoutMs: 30_000,
});

Option	Description
apiKey	Developer API secret key. Defaults to process.env.VIZBL_API_KEY.
baseURL	Developer API base URL. Defaults to process.env.VIZBL_BASE_URL, or https://api.vizbl.com.
timeoutMs	Optional timeout in milliseconds for API requests and direct uploads.
fetch	Optional custom Fetch API implementation.
defaultHeaders	Additional headers sent with Developer API requests.

API Reference

vizbl.objects.importModel(options)

Uploads one local model file or ordered model variants, creates an import job, and optionally waits for completion.

const job = await vizbl.objects.importModel({
  file: './chair.glb',
  name: 'Chair',
  wait: true,
});

Option	Description
file	Local path, Blob, ArrayBuffer, Uint8Array, or `{ path
variants	Ordered source variants for multi-variant imports. The first variant is the main/default variant. Use either variants or file.
name	Public object name. Defaults to the first file name without extension.
description	Optional public object description.
tags	Optional public object tags.
category	Optional Vizbl category id.
mechanic	Optional placement mechanic: all, floor, wall, or ceiling.
ai_generate	Requests best-effort AI preview generation when supported.
idempotencyKey	Optional key for safely retrying import job creation.
uploadConcurrency	Maximum number of variant files uploaded in parallel. Defaults to 2.
signal	Optional AbortSignal cancelling file resolution, presign, upload, and import job creation. Also cancels polling when wait is used without its own signal.
wait	Pass true to wait for completion, false/omit to return the queued job, or pass { pollIntervalMs, maxWaitMs, signal }.

When wait: true is used, the returned job includes tinuuid and url after a successful import.

const result = await vizbl.objects.importModel({
  name: 'Chair',
  variants: [
    { file: './chair-oak.glb', name: 'Oak' },
    { file: './chair-walnut.glb', name: 'Walnut' },
  ],
  wait: true,
});

console.log(result.tinuuid, result.url);

vizbl.objects.imports.create(request, options?)

Creates an import job from already uploaded source model variants. Use this when you want manual control over presign and direct upload.

const presign = await vizbl.uploads.presign({
  type: 'model_source',
  fileName: 'chair.glb',
  fileSize: 123456,
  fileType: 'model/gltf-binary',
});

// Upload the file to presign.uploadUrl with presign.uploadFields first.

const job = await vizbl.objects.imports.create({
  name: 'Chair',
  variants: [{ name: 'Default', uploadId: presign.uploadId }],
});

options.idempotencyKey sends the x-idempotency-key header.

vizbl.objects.imports.get(jobId)

Gets the current import job status, stage, warnings, error, tinuuid, and url when available.

const job = await vizbl.objects.imports.get('job-id');

vizbl.objects.imports.wait(jobId, options?)

Polls an import job until it succeeds, fails, times out, or is aborted.

const result = await vizbl.objects.imports.wait('job-id', {
  pollIntervalMs: 2_000,
  maxWaitMs: 15 * 60_000,
});

vizbl.objects.delete(tinuuid)

Deletes a published Vizbl object by public tinuuid.

await vizbl.objects.delete('tin_123');

vizbl.uploads.presign(request)

Creates a presigned upload session for a source model file. Most applications should use objects.importModel, which handles presign and upload internally.

const presign = await vizbl.uploads.presign({
  type: 'model_source',
  fileName: 'chair.glb',
  fileSize: 123456,
  fileType: 'model/gltf-binary',
});

Errors

The SDK throws VizblApiError for API, validation, auth, upload, and timeout failures. High-level import polling throws VizblImportError when a job fails or times out.

import { VizblApiError } from '@vizbl/node';

try {
  await vizbl.objects.importModel({ file: './chair.glb', wait: true });
} catch (error) {
  if (error instanceof VizblApiError && error.isAuthError()) {
    console.error('Check VIZBL_API_KEY');
  }
}

Development

pnpm install
pnpm generate
pnpm typecheck
pnpm test
pnpm build
pnpm validate

pnpm validate checks both @vizbl/node and @vizbl/mcp.

To refresh the OpenAPI schema from a deployed Developer API:

pnpm fetch-openapi
# or
VIZBL_OPENAPI_URL=https://api-dev.vizbl.com/developer-api/docs-json pnpm fetch-openapi

Local MCP Server

This repository also publishes @vizbl/mcp, a local stdio MCP server for agents like Codex and Claude Desktop. It uses @vizbl/node under the hood.

Codex:

codex mcp add vizbl \
  --env VIZBL_API_KEY=your_api_key \
  -- npx -y @vizbl/mcp

Claude Desktop:

{
  "mcpServers": {
    "vizbl": {
      "command": "npx",
      "args": ["-y", "@vizbl/mcp"],
      "env": {
        "VIZBL_API_KEY": "your_api_key"
      }
    }
  }
}

Available tools:

• vizbl_import_model
• vizbl_get_import
• vizbl_wait_import
• vizbl_delete_object

Note: vizbl_import_model defaults wait to true, the opposite of the SDK's objects.importModel default (false/omit), since agent workflows generally want the final result rather than a queued job id.

Architecture documentation

The cross-repository Remote MCP architecture, implementation plan, and team backlogs are documented in docs/remote-mcp/README.md.