画像セグメンテーションのためのSegmentLens APIの使用に関する完全なガイド。

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へのサイズ変更はセグメンテーション品質に影響しません。

推奨: 送信する前にクライアント側で画像のサイズを変更してください。返されたポリゴン座標を元の解像度にスケーリングできます。

少なくとも1つのテキストプロンプトが必要です。

リクエスト例

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にはレート制限があります。

制限: ユーザーあたり1秒間に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