README.md

metadata

title: SAM2 Segmentation API
emoji: 🎯
colorFrom: purple
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0

🎯 SAM2 Segmentation API

Мощный REST API для сегментации объектов на изображениях с использованием Meta SAM2 (Segment Anything Model 2).

✨ Возможности

• 🎯 Box Prompts - выделение прямоугольником
• 🖌️ Brush Prompts - рисование кистью (зеленый = объект, красный = фон, белый = объект)
• 📍 Point Prompts - клики по объектам
• 🔥 Batch API - обработка множественных объектов за один запрос
• 🖼️ Extract Objects - автоматическое извлечение объектов с прозрачностью
• ⚡ REST API - полная документация в Swagger UI

🚀 Быстрый старт

Web интерфейс

После запуска Space откройте:

• Простой интерфейс: /web - Box промпты
• Продвинутый: /web/advanced - Box + Brush промпты
• API документация: /docs - Swagger UI

API Endpoints

POST /segment/batch - Батчинг API (рекомендуется)

Обрабатывает множественные объекты за один запрос.

Пример запроса:

{
  "image": "data:image/jpeg;base64,...",
  "prompts": [
    {
      "id": 0,
      "type": "mask",
      "data": "data:image/png;base64,...",
      "label": "person",
      "selected": true
    }
  ],
  "options": {
    "extract_objects": true,
    "include_masks": false,
    "clean_masks": true
  }
}

POST /segment - Простая сегментация

С box промптом:

curl -X POST "/segment?box_x1=50&box_y1=50&box_x2=300&box_y2=400&extract_objects=true" \
  -F "file=@image.jpg"

📊 Производительность

⚠️ CPU Version: Работает на бесплатном CPU tier Hugging Face Spaces. Скорость обработки: ~5-10 секунд на изображение.

Для более быстрой обработки рекомендуется upgrade на GPU (Settings → Hardware).

🎨 Форматы масок

API поддерживает несколько форматов масок:

• 🟢 Зеленый (R<100, G>150, B<100) - foreground (объект)
• ⚪ Белый (R>200, G>200, B>200) - foreground (объект)
• 🔴 Красный (R>150, G<100, B<100) - background (исключить)

🔧 Технологии

• Meta SAM2 2.1 (Segment Anything Model)
• FastAPI
• PyTorch
• OpenCV
• Pydantic

📝 Примеры использования

Python

import requests
import base64

# Загрузить изображение
with open("image.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

# Отправить запрос
response = requests.post(
    "https://YOUR-SPACE.hf.space/segment/batch",
    json={
        "image": f"data:image/jpeg;base64,{image_b64}",
        "prompts": [{
            "id": 0,
            "type": "box",
            "data": "",
            "bbox": {"x_min": 0.1, "y_min": 0.2, "x_max": 0.5, "y_max": 0.8},
            "label": "person",
            "selected": True
        }],
        "options": {"extract_objects": True}
    }
)

result = response.json()
print(f"Обработано объектов: {len(result['results'])}")

JavaScript

const response = await fetch('https://YOUR-SPACE.hf.space/segment/batch', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    image: imageBase64,
    prompts: [{
      id: 0,
      type: "box",
      data: "",
      bbox: {x_min: 0.1, y_min: 0.2, x_max: 0.5, y_max: 0.8},
      label: "person",
      selected: true
    }],
    options: {extract_objects: true}
  })
});

const result = await response.json();
console.log(`Обработано: ${result.results.length} объектов`);

📚 Документация

Полная интерактивная документация доступна по адресу /docs после запуска Space.

🤝 Поддержка

• Модель: SAM 2.1 Hiera Tiny (для CPU)
• Форматы изображений: JPG, PNG, WEBP, BMP
• Максимальный размер: рекомендуется до 2048x2048px для разумной скорости

⚡ Оптимизация для мобильных приложений

1. Уменьшайте размер изображения перед отправкой (1024x1024)
2. Используйте include_masks: false если контуры не нужны
3. Кэшируйте результаты на клиенте
4. Используйте батчинг API для множественных объектов

📄 Лицензия

Apache 2.0

🔗 Ссылки

• SAM2 GitHub
• SAM2 Paper