API-Referenz

SegmentLens bietet eine leistungsstarke REST-API, mit der Sie unsere fortschrittlichen SAM3-Bildsegmentierungsfähigkeiten direkt in Ihre Anwendungen integrieren können.

Kostenlos starten — Konto erstellen und zu Einstellungen → API-Schlüssel navigieren, um Ihren Schlüssel sofort zu generieren. Neue Konten erhalten 5 kostenlose Credits (1 Credit = 1 API-Aufruf).

Zuerst in Aktion sehen? Kostenloses Online-Tool testen → · API-Demo ansehen →

Offizielle Demo

Wir stellen eine vollständige Node.js-Demo-Anwendung bereit, die zeigt, wie die SAM3-API integriert wird. Die Demo umfasst sowohl Backend-API-Integration als auch ein interaktives Frontend mit Objektvisualisierung und Download-Funktionen.

GitHub Repository: segmentany/sam3-nodejs-demo

Schnellstart

# Repository klonen
git clone https://github.com/segmentany/sam3-nodejs-demo.git
cd sam3-nodejs-demo

# Abhängigkeiten installieren
npm install

# API-Schlüssel konfigurieren
cp .env.example .env
# .env bearbeiten und setzen: SAM3_API_KEY=sk_live_your_actual_api_key_here

# Server starten
npm start
# Öffnen Sie http://localhost:3000

Authentifizierung

Alle API-Anfragen müssen mit einem API-Schlüssel authentifiziert werden.

So erhalten Sie Ihren Schlüssel:

Registrieren oder anmelden
Einstellungen → API-Schlüssel öffnen
API-Schlüssel generieren klicken — Ihr Schlüssel ist sofort bereit

Fügen Sie Ihren API-Schlüssel im Authorization-Header ein:

Authorization: Bearer sk_live_...

Halten Sie Ihren API-Schlüssel geheim. Veröffentlichen Sie ihn niemals in clientseitigem Code oder öffentlichen Repositories. Rotieren Sie ihn sofort unter Einstellungen → API-Schlüssel, falls er kompromittiert wird.

Endpunkte

Bild segmentieren

Bildsegmentierung auf einer bereitgestellten Bild-URL durchführen. Dieser Endpunkt unterstützt sowohl punkt- als auch boxbasiertes Prompting.

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

Request Body

Feld	Typ	Erforderlich	Beschreibung
`image`	`string`	Ja	Base64-kodierter Bild-String.
`prompts`	`string[]`	Ja	Ein Array von Text-Prompts zur Identifizierung der zu segmentierenden Objekte (z.B. ["cat", "dog"]).

Hinweis:

Limits: Max. Auflösung 1024x1024. Max. Base64-Payload 2MB. Bilder, die diese Limits überschreiten, werden abgelehnt.

Grund: Große Bilder benötigen zu lange und können zu Timeouts führen. Reduzierung auf 1024x1024 beeinträchtigt die Segmentierungsqualität nicht.

Empfehlung: Verkleinern Sie Bilder clientseitig vor dem Senden. Sie können die zurückgegebenen Polygon-Koordinaten auf die Originalauflösung zurückskalieren.

Mindestens ein Text-Prompt ist erforderlich.

Beispiel-Request

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-Beispiel

// server.js - Express Backend-Beispiel
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}`));

Frontend-Beispiel

// Clientseitige Bildverarbeitung und API-Aufruf
const MAX_SIZE = 1024;

async function segmentImage(file, prompts) {
  // Bild auf max 1024x1024 verkleinern
  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();

  // Masken-Koordinaten auf Originalauflösung zurückskalieren
  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

Die API gibt ein JSON-Objekt mit den Segmentierungsergebnissen im prompt_results-Array zurück.

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

Rate Limits

Die API ist ratenlimitiert, um faire Nutzung und Stabilität zu gewährleisten.

Limit: 10 Anfragen pro Sekunde pro Benutzer.

Bei Überschreitung erhalten Sie eine 429 Too Many Requests-Antwort.

Fehler

Die API verwendet Standard-HTTP-Statuscodes.

Statuscode	Beschreibung
`200`	OK. Anfrage erfolgreich.
`400`	Bad Request. Fehlende Pflichtfelder oder ungültiges Format.
`401`	Unauthorized. Ungültiger oder fehlender API-Schlüssel.
`402`	Payment Required. Unzureichende Credits.
`429`	Too Many Requests. Rate Limit überschritten.
`500`	Internal Server Error. Etwas ist auf unserer Seite schiefgelaufen.

Fehlerbehebung

"Unauthorized" oder 401

Prüfen Sie, ob SAM3_API_KEY korrekt gesetzt ist
Stellen Sie sicher, dass der Schlüssel gültig und aktiv ist
Starten Sie den Server nach Änderung von Umgebungsvariablen neu

"Image too large" oder 413

Die API erzwingt eine maximale Bildgröße und Payload-Größe
Die Demo verkleinert Bilder bereits, aber extrem große Bilder können Limits überschreiten
Versuchen Sie ein kleineres Quellbild oder reduzieren Sie MAX_SIZE

"Rate limit exceeded"

Sie senden Anfragen zu schnell mit demselben Schlüssel
Fügen Sie einfaches Throttling oder Queuing clientseitig hinzu

Server startet nicht

Prüfen Sie, ob Port 3000 bereits belegt ist
Versuchen Sie, PORT in server.js zu ändern
Stellen Sie sicher, dass Abhängigkeiten mit npm install installiert sind

Keine Objekte gefunden

Versuchen Sie andere Prompts (z.B. "person", "car", "tree")
Bestätigen Sie, dass das hochgeladene Bild die angeforderten Objekte enthält
Prüfen Sie den Netzwerk-Tab in Ihren Browser-Devtools auf API-Fehler

Code-Struktur

Das Demo-Projekt hat folgende Struktur:

sam3-nodejs-demo/
├── server.js          # Express Backend
├── package.json       # Abhängigkeiten und Skripte
├── .env.example       # Umgebungsvariablen-Vorlage
├── .env               # Lokale Umgebung (nicht committed)
├── .gitignore         # Git-Ignore-Regeln
└── public/
    └── index.html     # Frontend Single-Page-App

Bereit zum Bauen?

Kostenlosen API-Schlüssel erhalten → · 5 Credits inklusive · Keine Kreditkarte erforderlich

API-Referenz

On this page