API 참조

SegmentLens는 고급 SAM3 이미지 분할 기능을 애플리케이션에 직접 통합할 수 있는 강력한 REST API를 제공합니다.

공식 데모

SAM3 API를 통합하는 방법을 보여주는 완전한 Node.js 데모 애플리케이션을 제공합니다. 이 데모에는 백엔드 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 열기

인증

모든 API 요청은 API 키를 사용하여 인증해야 합니다. 대시보드의 설정 > API 키 섹션에서 API 키를 생성하고 관리할 수 있습니다.

요청의 Authorization 헤더에 API 키를 포함하세요:

Authorization: Bearer sk_live_...

엔드포인트

이미지 분할

제공된 이미지 URL에 대해 이미지 분할을 수행합니다. 이 엔드포인트는 포인트 기반 및 박스 기반 프롬프트를 모두 지원합니다.

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

요청 본문

필드	유형	필수	설명
`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(`Server running on port ${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);
  });
}

응답

API는 prompt_results 배열에 분할 결과를 포함하는 JSON 객체를 반환합니다.

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

속도 제한

공정한 사용과 안정성을 보장하기 위해 API에는 속도 제한이 있습니다.

제한: 사용자당 초당 10건의 요청.

이 제한을 초과하면 429 Too Many Requests 응답을 받게 됩니다.

오류

API는 표준 HTTP 상태 코드를 사용하여 요청의 성공 또는 실패를 나타냅니다.

상태 코드	설명
`200`	OK. 요청이 성공했습니다.
`400`	잘못된 요청. 필수 필드가 누락되었거나 잘못된 형식입니다.
`401`	승인되지 않음. 유효하지 않거나 누락된 API 키.
`402`	결제 필요. 크레딧이 부족합니다.
`429`	요청이 너무 많음. 속도 제한을 초과했습니다.
`500`	내부 서버 오류. 서버 측에서 문제가 발생했습니다.

문제 해결

"Unauthorized" 또는 401

SAM3_API_KEY가 올바르게 설정되었는지 확인하세요
키가 유효하고 활성 상태인지 확인하세요
환경 변수를 변경한 후 서버를 다시 시작하세요

"Image too large" 또는 413

API는 최대 이미지 크기와 페이로드 크기를 강제합니다
데모는 이미 이미지 크기를 조정하지만, 매우 큰 이미지는 여전히 제한을 초과할 수 있습니다
더 작은 원본 이미지로 시도하거나 MAX_SIZE를 줄이세요

"Rate limit exceeded"

동일한 키로 요청을 너무 빨리 보내고 있습니다
클라이언트 측에서 간단한 제한 또는 대기열을 추가하세요

서버가 시작되지 않음

포트 3000이 이미 사용 중인지 확인하세요
server.js에서 PORT를 변경해 보세요
npm install을 사용하여 의존성이 설치되었는지 확인하세요

객체를 찾을 수 없음 (No objects found)

다른 프롬프트(예: "person", "car", "tree")를 시도해 보세요
업로드된 이미지에 실제로 요청된 객체가 포함되어 있는지 확인하세요
브라우저 개발자 도구의 네트워크 탭에서 API 오류를 검사하세요

코드 구조

데모 프로젝트는 다음 구조를 따릅니다:

sam3-nodejs-demo/
├── server.js          # Express 백엔드
├── package.json       # 의존성 및 스크립트
├── .env.example       # 환경 변수 템플릿
├── .env               # 로컬 환경 (커밋되지 않음)
├── .gitignore         # Git 무시 규칙
└── public/
    └── index.html     # 프론트엔드 단일 페이지 앱

API 참조

On this page