> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API-Referenz

> Die öffentliche REST-API von Samsa — Basis-URL, Authentifizierung und Konventionen.

<Info>
  Diese Seite behandelt die Konventionen, die für jeden Endpoint gelten. Die
  vollständige, endpointweise Referenz — generiert aus der OpenAPI-Spezifikation
  der API — findest du in den Gruppen in der Seitenleiste:
  [Bildgenerierung](/de/api-reference/images/overview),
  [Bildbearbeitung](/de/api-reference/edits/overview),
  [Videogenerierung](/de/api-reference/videos/overview),
  [Modelltraining](/de/api-reference/model-training/overview),
  [Modelle](/de/api-reference/models/overview) und
  [Konto & Nutzung](/de/api-reference/account/overview). Ein funktionierendes
  End-to-End-Beispiel findest du im [Quickstart](/de/quickstart).
</Info>

## Basis-URL

```
https://api.samsa.ai/public/v1
```

## Authentifizierung

Jede Anfrage muss einen organisationsweiten API key als Bearer-Token mitführen:

```
Authorization: Bearer samsa_sk_your_key_here
```

Keys gehören der Organisation, sind mit Scopes versehen und werden nur einmal bei
der Erstellung angezeigt. Unter [Einen API key erstellen](/de/quickstart#einen-api-key-erstellen)
erfährst du, wie du einen bekommst.

## Konventionen

* **Asynchrone Jobs** — Generierungs-Endpoints geben `202 Accepted` mit einer
  Job-`id` zurück; frage den passenden `GET`-Endpoint nach dem Status ab oder gib
  eine `webhook_url` an, um bei Fertigstellung benachrichtigt zu werden.
* **Status** — Jobs durchlaufen `pending`, `processing` und dann einen terminalen
  Status `completed`, `failed` oder `cancelled`.
* **Scopes** — die meisten Endpoints benötigen einen Scope auf dem Key (zum
  Beispiel `images.generate`); `GET /me` braucht nur einen gültigen Key. Ein Key,
  dem ein erforderlicher Scope fehlt, erhält `403`.
* **Fehler** — Nicht-2xx-Antworten liefern einen strukturierten JSON-Fehlerkörper
  mit `type`, `code`, `message` und `request_id`.
* **Credits** — Aktionen ziehen aus dem Credit-Pool der Organisation; ein
  aufgebrauchter Pool liefert `402`.
* **Rate Limits** — Anfragen sind pro Key begrenzt; wird das Limit überschritten,
  liefert die API `429` mit einem `Retry-After`-Header.