Node.js Virtual Try-On SDK: Integration Walkthrough

If you are building an e-commerce backend, a headless commerce middleware, or an offline cron catalog generator, calling HTTP APIs directly can add boilerplate. The official Snapmydesign (SMD) Node.js/TypeScript SDK handles file streaming, automatic boundary headers, and custom exception handling with zero external dependencies.

This walkthrough outlines how to install, configure, and operate the NPM SDK package inside a Node.js runtime environment (v18+).

⚡ Getting Started in 3 Steps

1. Install the SDK Package

Add the official SDK dependency to your Node.js project:

bash

npm install snapit_sdk

2. Initialize the Client

Configure the client using your Developer API credentials from the Developer Console:

typescript

import { VTONClient } from 'snapit_sdk';

// Explicit configuration
const client = new VTONClient({
  apiKey: 'smd_live_your_api_key_here',
});

// Or use system environment variables (SMD_API_KEY)
// const client = new VTONClient();

3. Run the End-to-End Try-On Pipeline

Below is a complete TypeScript template to upload local asset files, trigger the try-on generation process, and handle errors:

typescript

import { VTONClient, InsufficientCreditsError, VTONError } from 'snapit_sdk';
import * as path from 'path';

const client = new VTONClient({
  apiKey: process.env.SMD_API_KEY || 'smd_live_...',
});

async function executeBackendFitting() {
  const userId = "your_developer_user_id";

  try {
    console.log("1. Checking system availability...");
    const health = await client.healthCheck();
    if (!health.success) {
      throw new Error("VTON services are currently offline");
    }

    console.log("2. Uploading local images to secure cloud storage...");
    // The SDK accepts file paths, Buffers, Blobs, or Files
    const uploadRes = await client.uploadImages(userId, [
      path.resolve(__dirname, './garment.png'),
      path.resolve(__dirname, './model.jpg')
    ], 1000); // 1000 is the optional resolution parameter

    const urls = uploadRes.uploaded.map(item => item.url);
    console.log("Uploaded asset URLs:", urls);

    console.log("3. Triggering try-on AI generation...");
    const generation = await client.generateTryOn({
      model_name: 'quality', // Options: "fast" (0.25 credits), "medium" (0.50 credits), "quality" (1.00 credit)
      inputClothesImageUrls: [urls[0]], // Garment asset URL
      inputPersonImageUrls: [urls[1]],  // Model / customer asset URL
      prompt: 'Fit this garment perfectly on the person',
      version: 1.1,
      productId: 'sku_dress_emerald_m',
      metadata: {
        department: 'Women'
      }
    });

    if (generation.success) {
      console.log("Fitting Completed Successfully!");
      console.log("Output Image URL:", generation.outputImageUrls[0]);
      console.log("Credits Expended:", generation.creditCost);
      console.log("Generation ID:", generation.generationId);
    }
  } catch (error) {
    if (error instanceof InsufficientCreditsError) {
      console.error("Billing failure: Your account has insufficient credits.");
    } else if (error instanceof VTONError) {
      console.error(`SDK VTONError (${error.statusCode}): ${error.message}`);
    } else {
      console.error("Unexpected error:", error);
    }
  }
}

executeBackendFitting();

🎨 SDK Service API Reference

The client instances expose high-level wrapper promises mapping to VTON core features:

Method	Parameters	Description
`healthCheck()`	None	Verifies status and health of the distributed VTON API clusters
`uploadImages()`	`userId`, `files[]`, `resolution?`	Uploads local file paths, streams, or buffers and returns cloud URLs
`generateTryOn()`	`VTONRequest` payload	Sends clothes and model URLs to trigger visual try-on generation
`getUserCredits()`	`userId`	Returns credit balance remaining for the specified developer account
`getHistory()`	`VTONHistoryParams`	Returns a paginated list of prior model generation history

💡 Error Matrix & Exception Handling

The SDK wraps standard HTTP error codes inside typed custom exceptions for simpler integration logging:

Important

Billing Safeguards: Always check your credit balances or handle InsufficientCreditsError exceptions. Generations using the quality model consume 1.00 credit per render, while medium consumes 0.50 and fast consumes 0.25 credits.

Tip

File Types: The uploadImages method automatically handles Node.js buffers and file streams. Ensure files uploaded are standard web extensions (.png, .jpg, .jpeg, .webp).