Schreibgeschützte API

Zugang und Verfügbarkeit

Dieser Leitfaden beschreibt die Vorabversion der schreibgeschützten API. Die Verfügbarkeit findest du unter API-Schlüssel in deinem Studio-Konto. Erforderlich ist ein aktives, bezahltes Studio- oder Scale-Abo; ein Guthabenpaket allein reicht nicht aus.

API-Abfragen verbrauchen keine Generierungsguthaben und funktionieren auch bei einem Guthaben von null. Diese Version bietet weder Foto-Uploads noch Generierung, Dateidownloads, Projektänderungen oder Abrechnungsverwaltung. Es handelt sich um eine HTTP-API, nicht um einen MCP-Server oder ein ChatGPT-Plugin.

Schlüssel erstellen und verbinden

1. Öffne API-Schlüssel in deinem Studio-Konto, benenne den Schlüssel nach deiner Integration und erstelle ihn. Jeder Schlüssel hat den Scope metadata:read.
2. Kopiere das Geheimnis sofort: Es wird nur einmal angezeigt. Speichere es serverseitig in einem Secret Manager oder in der Umgebungsvariablen SEGMENTIT_API_KEY.
3. Sende den Schlüssel über HTTPS im Header Authorization: Bearer. Das folgende Beispiel liest eine bereits gesetzte Umgebungsvariable; ersetze sie in geteiltem Code nicht durch ein Geheimnis.

cURL · Bash

curl --fail-with-body --get \
  'https://segmentit.com/api/v1/projects' \
  --data-urlencode 'limit=20' \
  --header \
  "Authorization: Bearer $SEGMENTIT_API_KEY"

Node.js · Serverseitiges JavaScript

Setze SEGMENTIT_API_KEY auf deinem Server und führe dieses Beispiel mit Node.js 22 oder neuer aus. Erstelle deinen Schlüssel unter Studio → Konto → API.

const apiKey = process.env.SEGMENTIT_API_KEY;
if (!apiKey) throw new Error('Set SEGMENTIT_API_KEY');

const response = await fetch(
  'https://segmentit.com/api/v1/projects?limit=20',
  {
    headers: { Authorization: `Bearer ${apiKey}` },
    redirect: 'error',
    signal: AbortSignal.timeout(10_000),
  },
);

if (!response.ok) {
  const retryAfter = response.headers.get('Retry-After');
  throw new Error(
    `API error: ${response.status}` +
    (retryAfter ? `; retry after ${retryAfter}s` : ''),
  );
}

const { data: projects, pagination } = await response.json();
console.log(projects);
console.log('Next offset:', pagination.nextOffset);

Verfügbare Endpunkte

Die Basis-URL lautet https://segmentit.com/api/v1. Jede Anfrage wird authentifiziert und ist auf die Daten des Schlüsselinhabers beschränkt. Verwende die von der API gelieferten UUIDs. JSON-Felder und Statuswerte bleiben in allen Sprachen auf Englisch.

Aufträge liefern den zuletzt gespeicherten Status: queued, running, succeeded, failed oder cancelled. Eine Abfrage kontaktiert den Verarbeitungsanbieter nicht und startet keine Arbeit. Aktualisiere das Projekt im Studio, wenn du den neuesten Verarbeitungsstand brauchst.

OpenAPI-Schema · JSON

Seitennavigation und Antworten

Listen geben data und pagination zurück. Der Standardwert für limit ist 20; zulässig sind 1–50 Einträge und ein offset von 0 bis 10000. Verwende nextOffset für die nächste Anfrage und höre bei null auf. Ein einzelnes Projekt oder ein Auftrag liefert nur ein data-Objekt. Datumsangaben verwenden ISO 8601.

{
  "data": [
    {
      "id": "7b5e26c3-e260-409a-bbb9-b5719f9dbfb0",
      "name": "Launch",
      "kind": "personal",
      "latestJobId": null,
      "createdAt": "2026-10-09T10:00:00.000Z",
      "updatedAt": "2026-10-09T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "nextOffset": null
  }
}

Limits, Fehler und Wiederholungen

Ein Konto kann 3 aktive Schlüssel haben. Sie laufen nach 90 Tagen ab. Alle Schlüssel teilen sich ein Limit von 60 Anfragen pro Minute und Konto. Warte bei einer 429-Antwort die in Retry-After angegebene Anzahl Sekunden, bevor du es erneut versuchst; vermeide ständige Abfragen.

Die Berechtigung wird bei jeder Anfrage geprüft. Erfüllt dein Abo die Voraussetzungen nicht mehr, antwortet die API mit 403, selbst wenn der Schlüssel noch gültig ist. Du kannst Schlüssel weiterhin im Studio widerrufen. Ein widerrufener oder abgelaufener Schlüssel liefert 401; erstelle einen Ersatz, sobald der Zugang verfügbar ist.

{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid API key is required."
  }
}

Integration sicher halten

Führe Anfragen auf deinem Server oder in einem vertrauenswürdigen lokalen Skript aus. Schlüssel gehören niemals in URLs, Browser-JavaScript, öffentliche Repositories, Screenshots oder Logs. Widerrufe einen offengelegten Schlüssel sofort. Ein Schlüssel kann Metadaten aller deiner Projekte lesen, nicht nur eines ausgewählten Projekts.

Antworten enthalten nur Metadaten: keine Quellfotos, Masken, GLB-Inhalte, Datei-URLs oder Anbieter-Zugangsdaten. Verwende weiterhin das Studio, um deine Kreationen anzusehen und herunterzuladen.