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

# Agent API

> Verwalte Krea-Agent-Sessions über HTTP: Starte eine Session, warte auf einen Zug, lies seine Ergebnisse und sende Folgenachrichten mit deinem API-Schlüssel.

Mit der Agent API gibst du Krea Agent eine Aufgabe aus deiner eigenen Anwendung. Anfragen und Antworten verwenden JSON-Felder in camelCase. Der Agent arbeitet im Hintergrund, während deine Anwendung seinen Fortschritt und seine Ergebnisse ausliest.

| Endpoint | Zweck |
| - | - |
| [`POST /agent/send-message`](/docs/api-reference/agent/send-agent-message) | Eine Session starten oder einen Folgezug senden. |
| [`GET /agent/session/{sessionId}`](/docs/api-reference/agent/get-agent-session) | Die aktuelle Session ohne Warten lesen. |
| [`POST /agent/wait-for-session`](/docs/api-reference/agent/wait-for-agent-session) | Bis zu einem Timeout warten, bis ein Zug abgeschlossen ist. |

<Warning>
  Der Agent arbeitet im Hintergrund. Er stellt keine Rückfragen, und Kosten- und Berechtigungsabfragen werden automatisch genehmigt. Nimm alle Anforderungen und Einschränkungen in deinen Prompt auf. Prüfe die Aufgabe, bevor du sie absendest.
</Warning>

## Authentifizierung, Zugriff und Abrechnung

Sende bei jeder Anfrage an `https://api.krea.ai` den Header `Authorization: Bearer KREA_API_KEY`. Persönliche, Service- und Legacy-API-Schlüssel verwenden die standardmäßige [Authentifizierung der öffentlichen API](/docs/de/developers/api-keys-and-billing).

Du kannst nur Sessions lesen oder fortsetzen, die dem authentifizierten Aufrufer im authentifizierten Workspace gehören. Die Kenntnis einer Session-ID gewährt keinen Zugriff. Angehängte Krea-Dateien müssen für diesen Aufrufer in diesem Workspace ebenfalls zugänglich sein.

<Info>
  Agent-Züge verbrauchen das Compute-Unit-Guthaben des Workspaces. Sie verbrauchen **nicht** das API-Guthaben. Die Berechtigungen des Agent-Plans und die Nachrichtenlimits des Free-Plans gelten weiterhin. Siehe [Agent: Pläne, Zugang und Credits](/docs/de/user-guide/agent/plans-and-credits).
</Info>

Jede Antwort enthält eine `url`, unter der du die Session in der Krea-App mit dem passenden Konto- und Workspace-Zugriff öffnen kannst.

## Eine Session starten und auf ihr Ergebnis warten

Setze zuerst `KREA_API_KEY` in deiner Umgebung. Wähle Bash mit `curl` und `jq`, Python mit `requests` oder Node.js mit dem integrierten `fetch` oder dem Krea SDK.

<Steps>
  <Step title="Den ersten Zug senden">
    Lass `sessionId` weg, um eine Session zu erstellen. Speichere die zurückgegebenen Werte `sessionId` und `runId`. Die Antwort kommt sofort mit `status: "running"` zurück.
  </Step>

  <Step title="Auf diesen Zug warten">
    Übergib beide IDs an `wait-for-session`. Wenn `timedOut` `true` ist, rufe den Endpoint erneut mit denselben IDs auf. Ein Timeout bricht den Zug nicht ab.
  </Step>

  <Step title="Das Ergebnis lesen">
    Prüfe `status`, wenn `finished` `true` ist. Sieh dir `text`, `media` und einen eventuellen `error` an oder öffne die zurückgegebene `url`.
  </Step>
</Steps>

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"vesper"}}
  set -euo pipefail
  : "${KREA_API_KEY:?Set your Krea API key}"

  START=$(curl --fail-with-body --silent --show-error --max-time 60 \
    https://api.krea.ai/agent/send-message \
    -H "Authorization: Bearer $KREA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Create three square product images for a ceramic coffee mug on a neutral studio background. Use no text or logos.",
      "name": "Coffee mug campaign"
    }')

  SESSION_ID=$(printf '%s' "$START" | jq -er '.sessionId')
  RUN_ID=$(printf '%s' "$START" | jq -er '.runId')
  printf '%s' "$START" | jq -r '.url'

  DEADLINE=$((SECONDS + 300))

  while (( SECONDS < DEADLINE - 10 )); do
    WAIT_SECONDS=$((DEADLINE - SECONDS - 10))
    if (( WAIT_SECONDS > 60 )); then WAIT_SECONDS=60; fi
    WAIT_BODY=$(jq -n --arg sessionId "$SESSION_ID" --arg runId "$RUN_ID" \
      --argjson timeoutSeconds "$WAIT_SECONDS" \
      '{sessionId: $sessionId, runId: $runId, timeoutSeconds: $timeoutSeconds}')
    RESULT=$(curl --fail-with-body --silent --show-error --max-time "$((WAIT_SECONDS + 10))" \
      https://api.krea.ai/agent/wait-for-session \
      -H "Authorization: Bearer $KREA_API_KEY" \
      -H "Content-Type: application/json" \
      -d "$WAIT_BODY")
    printf '%s' "$RESULT" | jq '{status, finished, timedOut, text, media, error, url}'
    if printf '%s' "$RESULT" | jq -e '.finished' > /dev/null; then
      if printf '%s' "$RESULT" | jq -e '.status == "completed"' > /dev/null; then
        exit 0
      fi
      printf '%s' "$RESULT" | jq -r '"Turn ended: \(.status). \(.error // "No error details")"' >&2
      exit 1
    fi
  done

  printf 'Wait budget exhausted; the turn continues. Resume waiting with sessionId=%s runId=%s\n' \
    "$SESSION_ID" "$RUN_ID" >&2
  exit 1
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"vesper"}}
  import json
  import os
  import time
  import requests

  api = "https://api.krea.ai"
  headers = {"Authorization": f"Bearer {os.environ['KREA_API_KEY']}"}

  response = requests.post(
      f"{api}/agent/send-message",
      headers=headers,
      json={
          "prompt": "Create three square product images for a ceramic coffee mug on a neutral studio background. Use no text or logos.",
          "name": "Coffee mug campaign",
      },
      timeout=60,
  )
  response.raise_for_status()
  start = response.json()
  session_id, run_id = start["sessionId"], start["runId"]
  print(start["url"])

  deadline = time.monotonic() + 300
  while True:
      wait_seconds = min(60, int(deadline - time.monotonic()) - 10)
      if wait_seconds < 1:
          raise TimeoutError(
              "Wait budget exhausted; the turn continues. Resume waiting with "
              f"sessionId={session_id} runId={run_id}"
          )
      response = requests.post(
          f"{api}/agent/wait-for-session",
          headers=headers,
          json={
              "sessionId": session_id,
              "runId": run_id,
              "timeoutSeconds": wait_seconds,
          },
          timeout=wait_seconds + 10,
      )
      response.raise_for_status()
      result = response.json()
      print(json.dumps(result, indent=2))
      if result["finished"]:
          if result["status"] != "completed":
              raise RuntimeError(
                  f"Turn ended: {result['status']}. {result.get('error', 'No error details')}"
              )
          break
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"vesper"}}
  import { performance } from "node:perf_hooks";

  const token = process.env.KREA_API_KEY;
  if (!token) throw new Error("Set your Krea API key");
  const api = "https://api.krea.ai";

  async function post(path, body, timeoutMs) {
    const response = await fetch(`${api}${path}`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(timeoutMs),
    });
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    }
    return response.json();
  }

  const start = await post("/agent/send-message", {
    prompt: "Create three square product images for a ceramic coffee mug on a neutral studio background. Use no text or logos.",
    name: "Coffee mug campaign",
  }, 60_000);
  const { sessionId, runId } = start;
  console.log(start.url);

  const deadline = performance.now() + 300_000;
  while (true) {
    const timeoutSeconds = Math.min(60, Math.floor((deadline - performance.now()) / 1000) - 10);
    if (timeoutSeconds < 1) {
      throw new Error(
        `Wait budget exhausted; the turn continues. Resume waiting with sessionId=${sessionId} runId=${runId}`,
      );
    }
    const result = await post("/agent/wait-for-session", {
      sessionId,
      runId,
      timeoutSeconds,
    }, (timeoutSeconds + 10) * 1000);
    console.log(JSON.stringify(result, null, 2));
    if (result.finished) {
      if (result.status !== "completed") {
        throw new Error(`Turn ended: ${result.status}. ${result.error ?? "No error details"}`);
      }
      break;
    }
  }
  ```

  ```javascript Node.js (SDK) theme={"theme":{"light":"github-light-default","dark":"vesper"}}
  import { performance } from "node:perf_hooks";
  import { Krea } from "@krea-ai/sdk";

  const token = process.env.KREA_API_KEY;
  if (!token) throw new Error("Set your Krea API key");
  const krea = new Krea({ apiKey: token });

  const start = await krea.requestRaw("/agent/send-message", {
    method: "POST",
    retry: false,
    signal: AbortSignal.timeout(60_000),
    body: {
      prompt: "Create three square product images for a ceramic coffee mug on a neutral studio background. Use no text or logos.",
      name: "Coffee mug campaign",
    },
  });
  const { sessionId, runId } = start;
  console.log(start.url);

  const deadline = performance.now() + 300_000;
  while (true) {
    const timeoutSeconds = Math.min(60, Math.floor((deadline - performance.now()) / 1000) - 15);
    if (timeoutSeconds < 1) {
      throw new Error(
        `Wait budget exhausted; the turn continues. Resume waiting with sessionId=${sessionId} runId=${runId}`,
      );
    }
    const result = await krea.requestRaw("/agent/wait-for-session", {
      method: "POST",
      retry: false,
      signal: AbortSignal.timeout((timeoutSeconds + 15) * 1000),
      body: { sessionId, runId, timeoutSeconds },
    });
    console.log(JSON.stringify(result, null, 2));
    if (result.finished) {
      if (result.status !== "completed") {
        throw new Error(`Turn ended: ${result.status}. ${result.error ?? "No error details"}`);
      }
      break;
    }
  }
  ```
</CodeGroup>

Installiere für Python `requests` mit `pip install requests`. Verwende für Node.js Node.js 22+ und speichere das Beispiel als `example.mjs`. Das SDK-Beispiel erfordert `npm install @krea-ai/sdk` und verwendet `requestRaw`, um die HTTP-Endpoints aufzurufen.

Diese Beispiele senden eine Nachricht und warten bis zu fünf Minuten. Sie brechen bei HTTP-Fehlern sowie bei fehlgeschlagenen oder abgebrochenen Zügen ab. Sie wiederholen einen Sendevorgang nie automatisch. Wenn bei einer Sendeanfrage ein Timeout auftritt, prüfe die Session in Krea, bevor du erneut sendest; die erste Anfrage hat möglicherweise bereits einen Zug gestartet.

Wenn das Warte-Budget abläuft, läuft der Zug im Hintergrund weiter. Speichere die ausgegebenen Session- und Run-IDs, um später weiter zu warten.

`timeoutSeconds` ist eine Ganzzahl von `1` bis `300` und hat den Standardwert `60`. Halte das Timeout deines HTTP-Clients länger als die angeforderte Wartezeit. Übergib beim Warten nach einem Sendevorgang immer die neueste `runId`, damit der Endstatus eines vorherigen Zugs nicht mit dem des neuen Zugs verwechselt wird.

### Ohne Warten lesen

Verwende `GET /agent/session/{sessionId}`, um einen Snapshot der aktuellen Session abzurufen:

```bash cURL theme={"theme":{"light":"github-light-default","dark":"vesper"}}
curl --fail-with-body --silent --show-error \
  "https://api.krea.ai/agent/session/$SESSION_ID" \
  -H "Authorization: Bearer $KREA_API_KEY"
```

### Die Session fortsetzen

Wenn der Zug abgeschlossen ist, sende eine weitere Nachricht mit seiner `sessionId`:

```bash cURL theme={"theme":{"light":"github-light-default","dark":"vesper"}}
FOLLOW_UP=$(curl --fail-with-body --silent --show-error \
  https://api.krea.ai/agent/send-message \
  -H "Authorization: Bearer $KREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg sessionId "$SESSION_ID" \
    '{sessionId: $sessionId, prompt: "Make a landscape variation of the first image."}')")

# Use this new runId in the next wait-for-session request.
RUN_ID=$(printf '%s' "$FOLLOW_UP" | jq -er '.runId')
```

Eine Session führt jeweils nur einen Zug aus. Wenn du eine weitere Nachricht sendest, während ein Zug läuft, wird `409` mit `code: "conflict"` zurückgegeben.

## Eingaben und Anhänge

`send-message` akzeptiert diese Felder. Das vollständige Modell-Enum und die Schemas findest du in der [Referenz](/docs/api-reference/agent/send-agent-message).

| Feld | Verhalten |
| - | - |
| `sessionId` | Optionale UUID. Weglassen für eine neue Session; angeben, um eine eigene Session fortzusetzen. |
| `prompt` | String mit bis zu 100.000 Zeichen. Standardwert: `""`. Ein nicht leerer Prompt oder mindestens ein Anhang ist erforderlich. |
| `attachments` | Bis zu 20 Anhänge. Standardwert: `[]`. Jeder benötigt eine `url` und kann `name` und `contentType` enthalten. |
| `model` | Optionale Agent-LLM-ID. Weglassen für Auto. Ein fixiertes Modell muss im Plan des Workspaces enthalten sein. |
| `effort` | Optional: `fast`, `default`, `high` oder `xhigh`. Neue Sessions verwenden standardmäßig `default`; weglassen, um den Effort einer bestehenden Session beizubehalten. |
| `name` | Optionaler Session-Name, nur für neue Sessions. Wird getrimmt, darf nicht leer sein und höchstens 120 Zeichen haben. |
| `desktopAppId` | Optionale UUID, die eine verbundene Desktop-App identifiziert. Führt diesen Zug in dieser App aus. Die App muss für den authentifizierten Aufrufer und Workspace verfügbar sein. |

Die `url` eines Anhangs akzeptiert eine zugängliche HTTP(S)-URL oder eine autorisierte Krea-Files-URI wie `file:550e8400-e29b-41d4-a716-446655440000`. Die optionalen Felder `name` und `contentType` sind getrimmte, nicht leere Strings mit bis zu 255 Zeichen. Lokale Pfade des Aufrufers und OpenAI-`file_`-IDs werden nicht unterstützt. Übertrage zuerst die eigentliche Datei; eine ID im Prompt-Text überträgt nicht deren Inhalt.

Der Agent übernimmt weder die Konversation noch die Anhänge deiner Anwendung. Hänge Referenzdateien an, die nicht anderweitig zugänglich sind. Nutzbare URLs im Prompt, vorhandener Krea-Kontext oder frühere Session-Dateien müssen nicht wiederholt werden.

## Session-Ergebnisse

`send-message` gibt `sessionId`, `threadId`, `runId`, `status` (immer `"running"`) und `url` zurück.

`GET /agent/session/{sessionId}` und `wait-for-session` geben die folgende Session-Ansicht zurück. Nur `wait-for-session` ergänzt das Pflichtfeld `timedOut`.

| Feld | Bedeutung |
| - | - |
| `sessionId`, `threadId` | IDs der Session und des Root-Threads. |
| `runId` | ID des aktuellen Zugs, sofern verfügbar. |
| `status` | `not_started`, `running`, `completed`, `failed` oder `cancelled`. |
| `finished` | `true` bei einem abgeschlossenen Zug. Wird beim Warten eine `runId` übergeben, muss der abgeschlossene Zug außerdem dieser ID entsprechen. |
| `text` | Text der neuesten Assistant-Nachricht. |
| `media` | Array der von der Session erzeugten Medien. Die Reihenfolge ist nicht relevant. |
| `error` | Optionaler Fehlertext für die Session. |
| `url` | Link zur Session in der Krea-App. |
| `timedOut` | Nur in Warte-Antworten: `true`, wenn die Frist abgelaufen ist, bevor der angeforderte Zug abgeschlossen war. |

Jedes `media`-Element kann eine Generierung (`jobId` und optional `mediaKind`: `image`, `video`, `audio` oder `3d`), neu gehostete Medien (`url`, optional mit `mimeType`) oder eine Krea-Datei (`uri`, `name`, `mimeType`) darstellen. Details zu einer Generierung rufst du über `GET /jobs/{jobId}` ab. Du kannst die URI einer Krea-Datei als Anhang wiederverwenden oder die `url` der Session öffnen, um ihre Dateien anzusehen. Medien können bereits erscheinen, während der Zug noch läuft.

## Fehler

Endpoint-Fehler verwenden `{ "error": "...", "code": "...", "allowedModels": ["..."] }`. Nur `error` ist erforderlich. Ein Zug, der nach dem Senden fehlschlägt, erscheint stattdessen als `status: "failed"` in einer erfolgreichen Session-Antwort.

| HTTP-Status | Bedeutung |
| - | - |
| `400` | Fehlerhafter JSON-Body. |
| `401` | Fehlende oder ungültige Authentifizierung. |
| `402` | Unzureichendes Compute-Unit-Guthaben im Workspace (`compute_limit`) oder Nachrichtenlimit des Free-Plans erreicht (`free_message_limit`). |
| `403` | Für das fixierte Modell besteht keine Berechtigung (`model_not_entitled`); `allowedModels` listet die zulässigen IDs auf. |
| `404` | Session fehlt oder ist nicht zugänglich (`not_found`), oder eine angehängte Krea-Datei fehlt oder ist nicht zugänglich (`attachment_not_found`). |
| `409` | Es läuft bereits ein Zug (`conflict`). |
| `422` | Ungültige Eingabe, oder die ausgewählte Desktop-App ist nicht verfügbar. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.