Skip to content

SDK Reference

SDK Methods and Usage

The following are the main public methods available in the Bodygram Headless SDK. All methods throw clear errors if required parameters are missing or invalid.

1. Initialization

const sdk = new BodygramSDK({
  clientKey: 'YOUR_CLIENT_KEY', // required
  locale: 'en',                // required
  container: '#my-container',   // optional: CSS selector or DOM element
  scanShouldIncludeOverlay: true, // optional: include tap overlay to prevent iOS audio issues
  // ...other config options
});
  • Throws if clientKey or locale is missing.
  • locale: See supported locales below
  • container: CSS selector string or DOM element where the scan UI will be embedded
  • scanShouldIncludeOverlay: When true, includes a tap overlay before scan UI to prevent iOS audio issues

2. scan()

const { front, side } = await sdk.scan();
- Opens the scan UI and returns base64-encoded front and side images. - Handles user cancellation and scan errors.

Example: Display captured images 

<div id="scan-results" style="display: none;">
  <h3>Captured Images</h3>
  <div style="display: flex; gap: 20px;">
    <div>
      <h4>Front View</h4>
      <img id="front-image" src="" alt="Front view" style="max-width: 300px;">
    </div>
    <div>
      <h4>Side View</h4>
      <img id="side-image" src="" alt="Side view" style="max-width: 300px;">
    </div>
  </div>
</div>

<script>
// After successful scan
const { front, side } = await sdk.scan();

// Display the images
document.getElementById('front-image').src = front;
document.getElementById('side-image').src = side;
document.getElementById('scan-results').style.display = 'block';
</script>

Note

The front and side images returned by sdk.scan() are base64-encoded strings representing the captured photos. You can use these strings to display the images or send them to your server. To display a base64 image on a webpage, you can set it as the src attribute of an <img> tag like this: <img src="BASE_64_IMAGE_STRING_RETURNED_BY_SDK">. Learn more about base64 image usage on MDN or see examples on Stack Overflow.

3. getBody2FitPhotoEstimation

This method uses AI-powered computer vision to analyze front and side photos of a user to estimate body measurements. It provides the most accurate measurements by analyzing the user's actual body shape and proportions.

When to use: For new users who can take photos, or when you need the most accurate body measurements.

const result = await sdk.getBody2FitPhotoEstimation({
  front,  // base64 string (required)
  side,   // base64 string (required)
  age,    // number, > 0 (required)
  gender, // 'male' or 'female' (required)
  height, // in mm, 500–2500 (required)
  weight, // in grams, 10000–200000 (required)
  // tightness, systemOfMeasurement, avatarType (optional)
});
- systemOfMeasurement (optional): "metric" (default) or "imperial" — determines the units for measurements. - avatarType (optional): "NO_AVATAR" (default) for no avatar, or "GLB" to receive a base64-encoded GLB avatar in the response. - Throws if any required field is missing or out of range.

Successful Response: 

{
    "estimations": {
        "estimationToken": {
            "token": "ESTIMATION_TOKEN"
        },
        "measurements": [
          {
            "estimationType": "ESTIMATION_TYPE",
            "value": "ESTIMATION_VALUE",
            "unit": "ESTIMATION_UNIT"
          },
          // ... more measurements
        ],
        "avatarData": null,
        "input": {
          "preferredSystemOfMeasurement": "METRIC",
          "tightness": 0,
          "inputType": "CAMERA_FLOW"
        }
    }
}
See all the measurements returned by the SDK in the measurements table below.

4. getBody2FitStatsEstimation

This method uses statistical modeling based on age, gender, height, and weight to estimate body measurements. It provides reasonable estimates without requiring photos, making it accessible for users who prefer not to take photos or when photo capture isn't available.

When to use: For users who prefer not to take photos, when photo capture isn't available, or as a fallback option. Provides good estimates but less accurate than photo-based estimation.

const result = await sdk.getBody2FitStatsEstimation({
  age,    // number, > 0 (required)
  gender, // 'male' or 'female' (required)
  height, // in mm, 500–2500 (required)
  weight, // in grams, 10000–200000 (required)
  // tightness, systemOfMeasurement, avatarType (optional)
});
- systemOfMeasurement (optional): "metric" (default) or "imperial" — determines the units for measurements. - avatarType (optional): "NO_AVATAR" (default) for no avatar, or "GLB" to receive a base64-encoded GLB avatar in the response. - Throws if any required field is missing or out of range.

Successful Response: 

{
    "estimations": {
        "estimationToken": {
            "token": "ESTIMATION_TOKEN"
        },
        "measurements": [
          {
            "estimationType": "ESTIMATION_TYPE",
            "value": "ESTIMATION_VALUE",
            "unit": "ESTIMATION_UNIT"
          },
          // ... more measurements
        ],
        "avatarData": null,
        "input": {
          "preferredSystemOfMeasurement": "METRIC",
          "tightness": 0,
          "inputType": "MANUAL_STATS"
        }
    }
}
See all the measurements returned by the SDK in the measurements table below.

5. getBody2FitTokenEstimation

The token estimation API is designed to provide a seamless experience for returning users. Instead of requiring users to repeat the entire photo scan or stats estimation process every time they need their measurements, developers can use the previously saved estimation token to retrieve the same measurement data. This eliminates friction in the user journey and improves the overall experience.

Learn more

See the Getting Started guide for detailed examples and use cases.

const result = await sdk.getBody2FitTokenEstimation({
  estimationToken, // string (required)
});
- Throws if estimationToken is missing.

Successful Response: 

{
    "estimations": {
        "estimationToken": {
            "token": "ESTIMATION_TOKEN"
        },
        "measurements": [
          {
            "estimationType": "ESTIMATION_TYPE",
            "value": "ESTIMATION_VALUE",
            "unit": "ESTIMATION_UNIT"
          },
          // ... more measurements
        ],
        "avatarData": null,
        "input": {
          "preferredSystemOfMeasurement": "METRIC",
          "tightness": 0,
          "inputType": "CAMERA_FLOW" // or "MANUAL_STATS" if you used stats-based estimation token
        }
    }
}
See all the measurements returned by the SDK in the measurements table below.

6. getBody2FitSizeRecommendation

This method provides the best size recommendation for a garment based on the user's body measurements. It analyzes the user's measurements against the garment's size chart and returns the most suitable size.

When to use: When you need a simple, clear size recommendation (e.g., "M", "L", "10", etc.) for display to users.

const result = await sdk.getBody2FitSizeRecommendation({
  estimationToken, // string (required)
  productInfo: [
    { brandId: 'BRAND_ID', garmentSku: 'GARMENT_SKU' }, // required
    // ...more products
  ]
});
- Throws if estimationToken or productInfo is missing, or if any product is missing brandId or garmentSku.

Successful Response: 

[
  {
    "recommendation": {
        "recommendedSize": "M" // Product 1 size recommendation
    }
  },
  {
    "recommendation": {
        "recommendedSize": "L" // Product 2 size recommendation
    }
  }
  // ... more product info
]

7. getBody2FitSizeFitting

This method provides detailed fitting analysis for multiple sizes of a garment. It returns comprehensive information about how each size fits the user, including tightness at specific fitting points (like bust, waist, hips, etc.) and recommendation rankings.

When to use: When you need detailed fitting information to show users how different sizes will fit them, or when you want to display specific fitting details like tightness at different body areas.

const result = await sdk.getBody2FitSizeFitting({
  estimationToken, // string (required)
  productInfo: [
    { brandId: 'BRAND_ID', garmentSku: 'GARMENT_SKU' }, // required
    // ...more products
  ]
});
- Throws if estimationToken or productInfo is missing, or if any product is missing brandId or garmentSku.

Successful Response: 

[
  {
    "result": {
      "estimationToken": {
        "token": "ESTIMATION_TOKEN"
      },
      "sizes": [
        {
          "size": {
            "index": 0,
            "name": "0"
          },
          "recommendationRank": 9,
          "fittingPoints": [
            {
              "fittingPoint": "ANKLE_DRESS_LENGTH",
              "tightness": 0
            },
            // ... more fitting points
          ],
          "tightness": 0,
          "neutralRecommendationRank": 9
        },
        // ... more sizes
      ],
      "sizeGroups": []
    }
  },
  // ... more product info
]

Locales supported by BodygramSDK's scan page

Code Language
ar Arabic
en English
es Spanish
es-419 Spanish (Latin America)
fr French
hi-IN Hindi
ja Japanese
pt Portuguese
pt-BR Portuguese (Brazil)
tr Turkish
vi Vietnamese
zh Chinese (Simplified)
zh-CN Chinese (Simplified)
zh-HK Chinese (Hong Kong)
zh-TW Chinese (Traditional)

All the measurements returned by the SDK

estimationType unit Description
AGE YEARS Age
GENDER GENDER Gender, '1' for male, '2' for female
WEIGHT GRAMS Weight
HEIGHT MILLIMETERS Height
ACROSS_BACK_SHOULDER_WIDTH MILLIMETERS Width across back between shoulders
BACK_NECK_HEIGHT MILLIMETERS Height of back neck point
BACK_NECK_POINT_TO_GROUND_CONTOURED MILLIMETERS Length from back neck to ground following body contour
BACK_NECK_POINT_TO_WAIST MILLIMETERS Length from back neck to waist
BACK_NECK_POINT_TO_WRIST_R MILLIMETERS Length from back neck to right wrist
BELLY_WAIST_GIRTH MILLIMETERS Circumference at belly waist
BELLY_WAIST_HEIGHT MILLIMETERS Height of belly waist
BUST_GIRTH MILLIMETERS Bust circumference
BUST_HEIGHT MILLIMETERS Height of bust point
CALF_GIRTH_R MILLIMETERS Right calf circumference
FOREARM_GIRTH_R MILLIMETERS Right forearm circumference
HIP_GIRTH MILLIMETERS Hip circumference
HIP_HEIGHT MILLIMETERS Height of hips
INSIDE_LEG_HEIGHT MILLIMETERS Height of inside leg
INSIDE_LEG_LENGTH_R MILLIMETERS Right inside leg length
KNEE_GIRTH_R MILLIMETERS Right knee circumference
KNEE_HEIGHT_R MILLIMETERS Height of right knee
MID_THIGH_GIRTH_R MILLIMETERS Right mid-thigh circumference
NECK_BASE_GIRTH MILLIMETERS Neck base circumference
NECK_GIRTH MILLIMETERS Neck circumference
OUTER_ANKLE_HEIGHT_R MILLIMETERS Height of right outer ankle
OUTER_ARM_LENGTH_R MILLIMETERS Right outer arm length
OUTSEAM_R MILLIMETERS Right outseam length
OUTSIDE_LEG_LENGTH_R MILLIMETERS Right outside leg length
SHOULDER_TO_ELBOW_R MILLIMETERS Right shoulder to elbow length
THIGH_GIRTH_R MILLIMETERS Right thigh circumference
TOP_HIP_GIRTH MILLIMETERS Top hip circumference
TOP_HIP_HEIGHT MILLIMETERS Height of top hip
UNDER_BUST_GIRTH MILLIMETERS Under bust circumference
UPPER_ARM_GIRTH_R MILLIMETERS Right upper arm circumference
WAIST_GIRTH MILLIMETERS Waist circumference
WAIST_HEIGHT MILLIMETERS Height of waist
WRIST_GIRTH_R MILLIMETERS Right wrist circumference