API 参考文档

SegmentLens 提供了一个强大的 REST API，允许您将我们先进的 SAM3 图像分割能力直接集成到您的应用程序中。

官方示例 (Official Demo)

我们提供了一个完整的 Node.js 示例应用，展示如何集成 SAM3 API。该示例包括后端 API 集成和带有对象可视化及下载功能的交互式前端。

GitHub 仓库: segmentany/sam3-nodejs-demo

快速开始

# 克隆仓库
git clone https://github.com/segmentany/sam3-nodejs-demo.git
cd sam3-nodejs-demo

# 安装依赖
npm install

# 配置 API 密钥
cp .env.example .env
# 编辑 .env 并设置: SAM3_API_KEY=sk_live_your_actual_api_key_here

# 启动服务
npm start
# 打开 http://localhost:3000

认证 (Authentication)

所有 API 请求都必须使用 API 密钥进行身份验证。您可以在仪表板的设置 > API 密钥部分生成和管理您的 API 密钥。

在请求的 Authorization 标头中包含您的 API 密钥：

Authorization: Bearer sk_live_...

端点 (Endpoints)

图像分割 (Segment Image)

对提供的图像 URL 执行图像分割。此端点支持基于点和基于框的提示。

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

请求体 (Request Body)

字段	类型	必填	描述
`image`	`string`	是	Base64 编码的图像字符串。
`prompts`	`string[]`	是	用于识别分割对象的文本提示数组（例如：["cat", "dog"]）。

注意:

限制: 最大分辨率 1024x1024。最大 Base64 载荷大小 2MB。超过限制的图像将被拒绝。

理由: 过大的图片会导致处理时间过长甚至超时。将图片缩放到 1024x1024 通常不会影响识别效果。

建议: 请在发送请求前在客户端对图片进行缩放处理。拿到返回结果后，您可以将多边形坐标按比例还原到原始尺寸。

至少需要提供一个文本提示。

请求示例

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 示例

// server.js - Express 后端示例
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(`服务运行在端口 ${PORT}`));

前端示例

// 客户端图片处理和 API 调用
const MAX_SIZE = 1024;

async function segmentImage(file, prompts) {
  // 将图片缩放到最大 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();
  
  // 将遮罩坐标还原到原始分辨率
  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)

API 返回一个 JSON 对象，其中 prompt_results 数组包含分割结果。

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

速率限制 (Rate Limits)

API 设有速率限制，以确保公平使用和稳定性。

限制: 每个用户每秒 10 个请求。

如果您超过此限制，您将收到 429 Too Many Requests 响应。

错误代码 (Errors)

API 使用标准 HTTP 状态代码来指示请求的成功或失败。

状态码	描述
`200`	OK。请求成功。
`400`	Bad Request。缺少必填字段或格式无效。
`401`	Unauthorized。API 密钥无效或缺失。
`402`	Payment Required。积分不足。
`429`	Too Many Requests。超出速率限制。
`500`	Internal Server Error。服务器内部错误。

故障排除 (Troubleshooting)

"Unauthorized" 或 401 错误

检查 SAM3_API_KEY 是否正确设置
确保密钥是有效且激活的
修改环境变量后重启服务

"Image too large" 或 413 错误

API 强制限制图片大小和载荷大小
示例代码已自动缩放图片，但特别大的图片仍可能超出限制
尝试使用更小的源图片或减小 MAX_SIZE 值

"Rate limit exceeded" 速率限制错误

您使用同一密钥发送请求过于频繁
在客户端添加简单的节流或队列机制

服务无法启动

检查端口 3000 是否被占用
尝试在 server.js 中修改 PORT
确保使用 npm install 安装了依赖

未找到对象

尝试不同的提示词（如 "person"、"car"、"tree"）
确认上传的图片确实包含请求的对象
在浏览器开发者工具的网络选项卡中检查 API 错误

代码结构 (Code Structure)

示例项目遵循以下结构：

sam3-nodejs-demo/
├── server.js          # Express 后端
├── package.json       # 依赖和脚本
├── .env.example       # 环境变量模板
├── .env               # 本地环境配置（不提交）
├── .gitignore         # Git 忽略规则
└── public/
    └── index.html     # 前端单页应用

API 参考文档

On this page