API Reference

SegmentLens provides a powerful REST API that allows you to integrate our advanced SAM3 image segmentation capabilities directly into your applications.

Official Demo

We provide a complete Node.js demo application showing how to integrate the SAM3 API. The demo includes both backend API integration and an interactive frontend with object visualization and download capabilities.

GitHub Repository: segmentany/sam3-nodejs-demo

Quick Start

# Clone the repository
git clone https://github.com/segmentany/sam3-nodejs-demo.git
cd sam3-nodejs-demo

# Install dependencies
npm install

# Configure your API key
cp .env.example .env
# Edit .env and set: SAM3_API_KEY=sk_live_your_actual_api_key_here

# Start the server
npm start
# Open http://localhost:3000

Authentication

All API requests must be authenticated using an API Key. You can generate and manage your API keys in the Settings > API Keys section of your dashboard.

Include your API key in the Authorization header of your requests:

Authorization: Bearer sk_live_...

Endpoints

Segment Image

Perform image segmentation on a provided image URL. This endpoint supports both point-based and box-based prompting.

URL: https://sam3.ai/api/v1/segment
Method: POST
Content-Type: application/json

Request Body

Field	Type	Required	Description
`image`	`string`	Yes	Base64 encoded image string.
`prompts`	`string[]`	Yes	An array of text prompts to identify objects to segment (e.g., ["cat", "dog"]).

Note:

Limits: Max resolution 1024x1024. Max Base64 payload size 2MB. Images exceeding these limits will be rejected.

Reason: Large images take too long to process and may time out. Resizing to 1024x1024 does not affect segmentation quality.

Recommendation: Resize images on your client side before sending. You can scale the returned polygon coordinates back to the original resolution.

At least one text prompt is required.

Example Request

curl -X POST https://sam3.ai/api/v1/segment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "image": "base64_encoded_image_string...",
    "prompts": ["cat", "sunglasses"]
  }'

Node.js Example

// server.js - Express backend example
const express = require('express');
const fetch = require('node-fetch');

const app = express();
app.use(express.json({ limit: '10mb' }));

const SAM3_API_URL = 'https://sam3.ai/api/v1/segment';
const SAM3_API_KEY = process.env.SAM3_API_KEY;

app.post('/api/segment', async (req, res) => {
  try {
    const response = await fetch(SAM3_API_URL, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${SAM3_API_KEY}`
      },
      body: JSON.stringify({
        image: req.body.image,
        prompts: req.body.prompts
      })
    });
    
    const data = await response.json();
    res.json(data);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

Frontend Example

// Client-side image processing and API call
const MAX_SIZE = 1024;

async function segmentImage(file, prompts) {
  // Resize image to max 1024x1024
  const resizedImage = await resizeImage(file, MAX_SIZE);
  
  const response = await fetch('/api/segment', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      image: resizedImage.base64,
      prompts: prompts
    })
  });
  
  const data = await response.json();
  
  // Scale mask coordinates back to original resolution
  const scaleFactor = resizedImage.scaleFactor;
  data.prompt_results.forEach(result => {
    result.predictions.forEach(pred => {
      pred.masks = pred.masks.map(mask => 
        mask.map(point => [point[0] / scaleFactor, point[1] / scaleFactor])
      );
    });
  });
  
  return data;
}

async function resizeImage(file, maxSize) {
  return new Promise((resolve) => {
    const img = new Image();
    img.onload = () => {
      let width = img.width;
      let height = img.height;
      let scaleFactor = 1;
      
      if (width > maxSize || height > maxSize) {
        scaleFactor = maxSize / Math.max(width, height);
        width *= scaleFactor;
        height *= scaleFactor;
      }
      
      const canvas = document.createElement('canvas');
      canvas.width = width;
      canvas.height = height;
      const ctx = canvas.getContext('2d');
      ctx.drawImage(img, 0, 0, width, height);
      
      resolve({
        base64: canvas.toDataURL('image/jpeg', 0.9).split(',')[1],
        scaleFactor: scaleFactor
      });
    };
    img.src = URL.createObjectURL(file);
  });
}

Response

The API returns a JSON object containing the segmentation results in the prompt_results array.

{
  "prompt_results": [
    {
      "echo": {
        "text": "cat"
      },
      "predictions": [
        {
          "label": "cat",
          "confidence": 0.98,
          "masks": [
            [
              [100, 100], [150, 100], [150, 150], [100, 150]
            ]
          ]
        }
      ]
    }
  ]
}

Rate Limits

The API is rate-limited to ensure fair usage and stability.

Limit: 10 requests per second per user.

If you exceed this limit, you will receive a 429 Too Many Requests response.

Errors

The API uses standard HTTP status codes to indicate the success or failure of a request.

Status Code	Description
`200`	OK. The request was successful.
`400`	Bad Request. Missing required fields or invalid format.
`401`	Unauthorized. Invalid or missing API Key.
`402`	Payment Required. Insufficient credits.
`429`	Too Many Requests. Rate limit exceeded.
`500`	Internal Server Error. Something went wrong on our end.

Troubleshooting

"Unauthorized" or 401

Verify SAM3_API_KEY is set correctly
Ensure the key is valid and active
Restart the server after changing environment variables

"Image too large" or 413

The API enforces a maximum image size and payload size
The demo already resizes images, but extremely large images may still exceed limits
Try with a smaller source image or reduce MAX_SIZE

"Rate limit exceeded"

You are sending requests too quickly with the same key
Add simple throttling or queuing on the client side

Server does not start

Check whether port 3000 is already in use
Try changing PORT in server.js
Ensure dependencies are installed with npm install

No objects found

Try different prompts (e.g. "person", "car", "tree")
Confirm the uploaded image actually contains the requested objects
Inspect network tab in your browser devtools for API errors

Code Structure

The demo project follows this structure:

sam3-nodejs-demo/
├── server.js          # Express backend
├── package.json       # Dependencies and scripts
├── .env.example       # Environment variables template
├── .env               # Local environment (not committed)
├── .gitignore         # Git ignore rules
└── public/
    └── index.html     # Frontend single-page app

API Reference

On this page