> ## 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.

# Quickstart

> Erstelle einen API key und generiere dein erstes Bild mit einem trainierten style-Modell in fünf Schritten.

Dieser Guide bringt dich in fünf Schritten von null zu einem fertigen Bild:
erstelle einen Key, verifiziere ihn, reiche eine Generierung ein, frage das
Ergebnis ab und lade es herunter. Jeder Aufruf zielt auf die Base URL:

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

<Note>
  Die Beispiele verwenden einen fiktiven Key (`samsa_sk_example…`) und
  Platzhalter-ids. Ersetze sie durch deine eigenen. Speichere deinen Key in einer
  Umgebungsvariablen, damit er nie in der Versionsverwaltung landet:

  ```bash theme={null}
  export SAMSA_API_KEY="samsa_sk_exampleXf9Lp2QyaBcDeFgHiJkLmNoPqRsTuVwx"
  ```
</Note>

## Einen API key erstellen

API keys gehören der **Organisation** und können nur von einem
Organisations-**Admin** (`OWNER` oder `ADMIN`) erstellt werden.

<Steps>
  <Step title="Öffne deine Organisationseinstellungen">
    Gehe in der [Samsa-App](https://app.samsa.ai) zu deinen
    Organisationseinstellungen und öffne den Tab **API Keys**.
  </Step>

  <Step title="Erstelle einen Key">
    Gib dem Key einen Namen. Standardmäßig erhält er **alle Scopes**
    (`images.generate`, `images.edit`, `videos.generate`, `models.read`,
    `models.write`, `usage.read`); schränke sie ein, wenn die Integration weniger
    braucht. Du kannst auch ein optionales Ablaufdatum festlegen.
  </Step>

  <Step title="Kopiere den Key jetzt">
    <Warning>
      Der vollständige Key (`samsa_sk_…`) wird **genau einmal** angezeigt, bei der
      Erstellung. Samsa speichert nur einen Hash und kann ihn nie wieder anzeigen.
      Kopiere ihn sofort und bewahre ihn sicher auf — wenn du ihn verlierst,
      widerrufe den Key und erstelle einen neuen.
    </Warning>
  </Step>
</Steps>

Keys handeln **für ihre Organisation**: Credits werden aus dem Pool der
Organisation gezogen, und alle Bilder oder Videos, die du generierst, erscheinen
in der App unter dem Konto des Admins, der den Key erstellt hat.

## Den Key mit `GET /me` verifizieren

`GET /me` ist der schnellste Weg, zu bestätigen, dass ein Key funktioniert. Der
Endpoint gibt die Organisation des Keys, seine sicheren Metadaten (prefix, scopes,
Ablaufdatum — nie das Secret) und das verfügbare Credit-Guthaben der Organisation
zurück.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.samsa.ai/public/v1/me \
    -H "Authorization: Bearer $SAMSA_API_KEY"
  ```

  ```python Python theme={null}
  import os
  import requests

  BASE_URL = "https://api.samsa.ai/public/v1"
  API_KEY = os.environ["SAMSA_API_KEY"]
  HEADERS = {"Authorization": f"Bearer {API_KEY}"}

  resp = requests.get(f"{BASE_URL}/me", headers=HEADERS)
  resp.raise_for_status()
  print(resp.json())
  ```

  ```typescript TypeScript theme={null}
  const BASE_URL = "https://api.samsa.ai/public/v1";
  const API_KEY = process.env.SAMSA_API_KEY!;
  const headers = { Authorization: `Bearer ${API_KEY}` };

  const resp = await fetch(`${BASE_URL}/me`, { headers });
  if (!resp.ok) throw new Error(`GET /me failed: ${resp.status}`);
  console.log(await resp.json());
  ```
</CodeGroup>

```json Response theme={null}
{
  "organization": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Acme Inc"
  },
  "api_key": {
    "id": "9c8d7e6f-5a4b-4c3d-2e1f-0a9b8c7d6e5f",
    "name": "Production key",
    "prefix": "samsa_sk_exam",
    "scopes": [
      "images.edit",
      "images.generate",
      "models.read",
      "models.write",
      "usage.read",
      "videos.generate"
    ],
    "expires_at": null
  },
  "credits": {
    "available": 1450
  }
}
```

## Ein Bild generieren

Reiche einen Prompt an `POST /images/generations` ein. Hier komponieren wir
außerdem eines der trainierten **style**-Modelle der Organisation, indem wir seine
id oder seinen Namen als `style_id` übergeben — ein Name wird zu einem für dich
sichtbaren Modell aufgelöst. Du kannst `object_ids`, `person_ids`, `setting_ids`
und eine `color_palette_id` auf dieselbe Weise kombinieren — jeweils per Name
oder id. Die Anfrage gibt sofort `202` mit einer Job-`id` zurück; das Bild wird
asynchron produziert.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.samsa.ai/public/v1/images/generations \
    -H "Authorization: Bearer $SAMSA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "A minimalist product shot of a ceramic mug on linen, soft daylight",
      "style_id": "2b9d1f7a-3c4e-4a5b-9c8d-0e1f2a3b4c5d",
      "aspect_ratio": "1:1",
      "resolution": "1K",
      "num_outputs": 1
    }'
  ```

  ```python Python theme={null}
  payload = {
      "prompt": "A minimalist product shot of a ceramic mug on linen, soft daylight",
      "style_id": "2b9d1f7a-3c4e-4a5b-9c8d-0e1f2a3b4c5d",
      "aspect_ratio": "1:1",
      "resolution": "1K",
      "num_outputs": 1,
  }

  resp = requests.post(
      f"{BASE_URL}/images/generations",
      headers={**HEADERS, "Content-Type": "application/json"},
      json=payload,
  )
  resp.raise_for_status()
  job = resp.json()
  generation_id = job["id"]
  print(job)
  ```

  ```typescript TypeScript theme={null}
  const payload = {
    prompt: "A minimalist product shot of a ceramic mug on linen, soft daylight",
    style_id: "2b9d1f7a-3c4e-4a5b-9c8d-0e1f2a3b4c5d",
    aspect_ratio: "1:1",
    resolution: "1K",
    num_outputs: 1,
  };

  const submit = await fetch(`${BASE_URL}/images/generations`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
  if (!submit.ok) throw new Error(`generation failed: ${submit.status}`);
  const job = await submit.json();
  const generationId = job.id;
  console.log(job);
  ```
</CodeGroup>

```json Response — 202 Accepted theme={null}
{
  "id": "7f9c0e2a-1b3d-4c5e-8f6a-9b0c1d2e3f40",
  "status": "pending",
  "estimated_credits": 5
}
```

<Note>
  Die Standard-Engine ist `nano_banana_pro` (übergib `engine`, um
  `nano_banana_2` zu wählen). `num_outputs` ist standardmäßig **1**; jedes Ergebnis
  (output) kostet `5` Credits bei `1K` und skaliert mit der Auflösung (`1K` ×1,
  `2K` ×2, `4K` ×4). Die `style_id` — eine id oder ein Name — muss auf ein für
  dich sichtbares `completed`-Modell verweisen.
</Note>

## Das Ergebnis abfragen

Frage `GET /images/generations/{id}` ab, bis `status` gleich `completed` (oder
`failed`) ist. Die Status sind `pending`, `processing`, `completed`, `failed` und
`cancelled`.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.samsa.ai/public/v1/images/generations/7f9c0e2a-1b3d-4c5e-8f6a-9b0c1d2e3f40 \
    -H "Authorization: Bearer $SAMSA_API_KEY"
  ```

  ```python Python theme={null}
  import time

  while True:
      resp = requests.get(
          f"{BASE_URL}/images/generations/{generation_id}",
          headers=HEADERS,
      )
      resp.raise_for_status()
      result = resp.json()
      if result["status"] in ("completed", "failed", "cancelled"):
          break
      time.sleep(2)

  print(result)
  ```

  ```typescript TypeScript theme={null}
  async function poll(id: string) {
    while (true) {
      const resp = await fetch(`${BASE_URL}/images/generations/${id}`, { headers });
      if (!resp.ok) throw new Error(`poll failed: ${resp.status}`);
      const result = await resp.json();
      if (["completed", "failed", "cancelled"].includes(result.status)) {
        return result;
      }
      await new Promise((r) => setTimeout(r, 2000));
    }
  }

  const result = await poll(generationId);
  console.log(result);
  ```
</CodeGroup>

```json Response — completed theme={null}
{
  "id": "7f9c0e2a-1b3d-4c5e-8f6a-9b0c1d2e3f40",
  "status": "completed",
  "created_at": "2026-07-02T12:00:00Z",
  "credits_used": 5,
  "images": [
    {
      "id": "d4c3b2a1-6f5e-4b3a-9d8c-1e0f2a3b4c5d",
      "url": "https://cdn.samsa.ai/user-.../7f9c0e2a.png?X-Amz-Signature=...",
      "thumbnail_url": "https://cdn.samsa.ai/user-.../7f9c0e2a-thumb.png?X-Amz-Signature=...",
      "width": 1024,
      "height": 1024,
      "seed": 128390
    }
  ],
  "error": null
}
```

## Das Ergebnis herunterladen

Jeder Eintrag in `images` trägt eine presigned HTTPS-`url`, die **24 Stunden**
gültig ist — lade das Asset herunter und speichere es, bevor es abläuft.

<CodeGroup>
  ```bash curl theme={null}
  curl -o mug.png \
    "https://cdn.samsa.ai/user-.../7f9c0e2a.png?X-Amz-Signature=..."
  ```

  ```python Python theme={null}
  image_url = result["images"][0]["url"]
  img = requests.get(image_url)
  img.raise_for_status()
  with open("mug.png", "wb") as f:
      f.write(img.content)
  ```

  ```typescript TypeScript theme={null}
  const imageUrl = result.images[0].url;
  const img = await fetch(imageUrl);
  const buffer = Buffer.from(await img.arrayBuffer());
  await import("node:fs/promises").then((fs) => fs.writeFile("mug.png", buffer));
  ```
</CodeGroup>

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="API-Referenz" icon="terminal" href="/de/api-reference/introduction">
    Die Base URL, die Authentifizierung und die Konventionen, die jeder Endpoint
    teilt.
  </Card>

  <Card title="MCP server" icon="plug" href="/de/mcp-server">
    Verbinde Samsa mit Claude, ChatGPT oder einem beliebigen MCP client und
    generiere Medien als Tools — über OAuth oder einen API key.
  </Card>
</CardGroup>

<Tip>
  Lieber Push statt Polling? Übergib bei jeder Generierungsanfrage eine
  `webhook_url`, um in dem Moment, in dem der Job einen terminalen Status erreicht,
  einen signierten Callback zu erhalten.
</Tip>