API 参考文档

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

免费开始 — 创建账号并前往设置 → API Keys 立即生成密钥。新账号赠送 5 个免费额度（1 额度 = 1 次 API 调用）。

官方示例 (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 Keys
点击生成 API Key — 密钥立即就绪

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

Authorization: Bearer sk_live_...

请妥善保管您的 API 密钥。切勿在客户端代码或公开仓库中暴露密钥。如发生泄露，请立即前往设置 → API Keys 轮换密钥。

端点 (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"]）。

注意:

请提交 Base64 编码图片。image 字符串不得超过 2,097,152 个字符（编码前约 1.5 MiB）。建议等比例缩放至 1024×1024 以内；这是处理建议，并非独立的像素尺寸校验，大图可能超时。

缩放可减少上传体积和处理时间，但可能丢失细节。按源图分辨率导出不会恢复分割阶段已丢失的细节。

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

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

请求示例

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]
            ]
          ]
        }
      ]
    }
  ]
}

点选/框选分割 (PVS)

每次请求交互式分割一个对象。你可以提供正/负点、以中心为锚点的矩形框，或同时提供两者；坐标均为图片像素坐标，不需要文字提示词。

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

请求体 (Request Body)

字段	类型	必填	描述
`image`	`string`	是	Base64 编码的图片字符串。限制同 `/v1/segment`。
`points`	`Point[]`	条件必填	图片像素坐标中的点提示。未提供 `box` 时必填，并且至少包含一个正点。
`box`	`Box`	条件必填	图片像素坐标中的中心锚定矩形框。未提供 `points` 时必填，也可与点同时使用。
`imageId`	`string`	否	可选的稳定图片 ID，跨请求复用同一张图片时可加速处理。
`multimaskOutput`	`boolean`	否	默认 `true`；设为 `false` 则只返回最优蒙版。

Point 结构：

字段	类型	必填	描述
`x`	`number`	是	X 像素坐标（≥ 0）。
`y`	`number`	是	Y 像素坐标（≥ 0）。
`positive`	`boolean`	否	`true`（默认）= 保留该区域；`false` = 排除该区域。

Box 结构为 { x, y, width, height }；x、y 表示矩形框中心，与 Roboflow PVS 契约一致。

提示: 混合正/负点可以精修复杂蒙版（例如选中人物但排除他手里拿的物体）。

请求示例

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

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();

响应

返回与 Roboflow visual_segment 相同的 JSON 形状 —— prompts 数组中包含 predictions，每个 masks 多边形为图片像素坐标。设置 multimaskOutput: false 可只接收单个蒙版。

计费

每次成功请求消耗 sam3:visual 配置的积分（当前 每次调用 1 积分，与点数无关）。失败（上游/5xx）自动退款。

速率限制 (Rate Limits)

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

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

如果您超过此限制，您将收到 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 值

服务无法启动

检查端口 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     # 前端单页应用

两个接口均支持 Idempotency-Key 请求头（1–128 个字母、数字或 . _ : -）。连接中断后，用同一请求体和同一键重试；24 小时内复用已保存结果，不再扣除账户积分。同一键更换请求体返回 409；请求仍在执行或退款待完成时也返回 409，并提供 Retry-After。新键代表新的付费尝试。不提供键时，相同请求复用五分钟内的结果；X-Force-Refresh: true 明确发起新尝试。显式幂等键优先于强制刷新。

上游失败、无效结果和空蒙版均按原扣费流水退款。API Key 空结果保留成功响应结构，X-SAM3-Refunded: true 表示补偿已完成；退款失败会保留记录继续补偿。x402 空结果返回 422，不结算付款。响应包含 X-SAM3-Request-ID。文本提示最多 16 项，每项 1–500 字符；点提示最多 1,024 项。

API 参考文档

API 参考文档

官方示例 (Official Demo)

快速开始

认证 (Authentication)

端点 (Endpoints)

图像分割 (Segment Image)

请求体 (Request Body)

请求示例

Node.js 示例

前端示例

响应 (Response)

点选/框选分割 (PVS)

请求体 (Request Body)

请求示例

Node.js 示例

响应

计费

速率限制 (Rate Limits)

错误代码 (Errors)

故障排除 (Troubleshooting)

"Unauthorized" 或 401 错误

"Image too large" 或 413 错误

"Rate limit exceeded" 速率限制错误

服务无法启动

未找到对象

代码结构 (Code Structure)

准备好构建了吗？

请求恢复与计费

On this page