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.

How to get your key:

1. Sign up or log in
2. Open Settings → API Keys
3. Click Generate API Key — your key is ready immediately

Include your API key in the Authorization header:

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

Note:

1. Send a Base64-encoded image. The image string must not exceed 2,097,152 characters (about 1.5 MiB before Base64 encoding). Resizing to fit within 1024×1024 is recommended, not a separate pixel-dimension check; larger images may time out.
   • Resizing reduces upload size and processing time, but can lose fine detail. Exporting at source-image resolution does not restore detail lost during segmentation.
   • Recommendation: Resize images on your client side before sending. You can scale the returned polygon coordinates back to the original resolution.
2. 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]
            ]
          ]
        }
      ]
    }
  ]
}

Point/Box Visual Segment (PVS)

Interactive segmentation endpoint for one object per request. Give the model positive/negative points, a center-anchored bounding box, or both in image-pixel coordinates. No text prompt is needed.

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

Request Body

Point shape:

Box is { x, y, width, height }; x and y are the box center, matching the Roboflow PVS contract.

Tip: Combine include/exclude points to refine a tricky mask. For example, one positive point on a person plus one negative point on the object they're holding will exclude that object from the result.

Example Request

curl -X POST https://sam3.ai/api/v1/pvs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "image": "base64_encoded_image_string...",
    "points": [
      { "x": 412, "y": 318, "positive": true },
      { "x": 540, "y": 290, "positive": false }
    ]
  }'

Node.js Example

const res = await fetch("https://sam3.ai/api/v1/pvs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.SAM3_API_KEY}`,
  },
  body: JSON.stringify({
    image: base64Image,
    points: [{ x: 412, y: 318, positive: true }],
  }),
});
const data = await res.json();

Response

Returns the same JSON shape used by Roboflow visual_segment — a prompts array with predictions containing masks polygons in image-pixel coordinates. Pass multimaskOutput: false if you only want a single mask.

Pricing

Each successful request consumes the credits configured under sam3:visual (currently 1 credit per call, regardless of point count). Failures (upstream / 5xx) are automatically refunded.

Rate Limits

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

• Limit: 3 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.

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

Ready to build?

Request recovery and billing

For both endpoints, send an Idempotency-Key header (1–128 letters, digits, ., _, :, or -). Reuse it with the same body after a connection failure. For 24 hours, completed requests replay the saved result without another account-credit charge. A changed body returns 409; a request still processing or awaiting refund also returns 409 with Retry-After. A new key starts a new paid attempt. Without a key, identical requests share a result for five minutes; X-Force-Refresh: true explicitly starts a new attempt. An explicit key takes precedence over force refresh.

Upstream failures, invalid results and empty masks refund the original account debit. Empty API-key results retain their successful response shape; X-SAM3-Refunded: true confirms completed compensation. Failed refunds remain pending for recovery. x402 empty results return 422 and are not settled. Responses include X-SAM3-Request-ID. Text prompts are limited to 16 entries of 1–500 characters; point prompts to 1,024 entries.