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

# Erste Schritte

> API-Schlüssel einrichten und mit cURL Angebot, Ausführung und Ergebnisabruf ausprobieren.

## Überblick

Dieses Beispiel führt mit `web_search` von der Schlüsselvorbereitung über ein kostenloses Angebot zur Ausführung und zum Ergebnis. Sie benötigen nur eine Bash-kompatible Shell und cURL, kein sprachspezifisches SDK.

## Voraussetzungen

Bereiten Sie vor dem API-Aufruf Folgendes vor:

* Ein NoimosAI-Konto mit Zugang zur [Developer Platform](https://platform.noimosai.com)
* Ein Developer-Platform-Projekt mit aktiviertem API-Zugriff
* Ein Entwickler-API-Schlüssel mit Präfix `nmp_` und erforderlichen Berechtigungen
* Eine Bash-kompatible Shell
* cURL, jq und uuidgen

Prüfen Sie für kostenpflichtige Aufträge auch verfügbares USD-Prepaid-Guthaben und monatliche Projektlimits. Schlüsselberechtigungen erläutert [Anfragen authentifizieren](https://docs.noimosai.com/de/developers/api/authentication.md).

Wird kein zugängliches Projekt angezeigt, bitten Sie einen `OWNER` oder `ADMIN` der Organisation, ein Projekt anzulegen oder Sie hinzuzufügen. API-Schlüssel erstellen Sie innerhalb eines Projekts, dem Sie angehören.

## API ausführen

Ihre erste Ausführung erfolgt in sieben Schritten.

### 1. API-Schlüssel in der Developer Platform erstellen

Ein Projektmitglied mit Rolle `ADMIN` oder `DEVELOPER` kann in der [Developer Platform](https://platform.noimosai.com) so einen Schlüssel erstellen:

1. An der Developer Platform anmelden und ein Projekt auswählen.
2. **API-Schlüssel** öffnen und **Neuen Schlüssel erstellen** wählen.
3. Aussagekräftigen Namen, Ablaufdatum und benötigte Berechtigungen festlegen und den Schlüssel erstellen.
4. Den nur einmal angezeigten geheimen Schlüssel sicher speichern.

Für diese Anleitung benötigen Sie `project:read`, `tools:read`, `tools:execute` und `executions:read`. Wählen Sie für andere Zwecke nur benötigte Berechtigungen.

### 2. API-Schlüssel und Basis-URL setzen

Speichern Sie API-Schlüssel und Basis-URL in Umgebungsvariablen, damit Geheimnisse nicht direkt im Befehlsverlauf oder Quellcode stehen.

```bash theme={null}
export NOIMOS_PLATFORM_API_URL="https://api.noimosai.com/noimosToolBridge"
export NOIMOS_PLATFORM_API_KEY="nmp_..."
```

> [!WARNING]
>
> Der Schlüssel wird nur bei Erstellung einmal angezeigt. Speichern Sie ihn nicht in Git-Repositories, geteilten Dokumenten oder clientseitigem JavaScript.

### 3. Projekt des Schlüssels prüfen

Prüfen Sie zuerst, ob der Schlüssel zum vorgesehenen Developer-Platform-Projekt gehört.

```bash theme={null}
curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/project" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY"
```

Bei Erfolg enthält `data` Organisations-ID, Projekt-ID und Projektname. Ist es nicht das erwartete Projekt, prüfen Sie den Schlüssel vor kostenpflichtigen Aufträgen.

```json theme={null}
{
  "data": {
    "developerOrganizationId": "...",
    "developerProjectId": "...",
    "name": "Example Project"
  },
  "requestId": "..."
}
```

### 4. Verfügbare Tools prüfen

Rufen Sie aktuelle Toolnamen, Beschreibungen, Eingabeschemas, Beispiele, Verfügbarkeit und Preise ab.

```bash theme={null}
NOIMOS_TOOLS_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

echo "$NOIMOS_TOOLS_RESPONSE" | jq
```

Prüfen Sie `executionEnabled` für die gesamte Antwort und `available` für das Tool. Nutzen Sie diese Antwort als aktuelle Grundlage, statt Toolanzahl, Modelle, Schemas oder Preise fest anzunehmen.

Filtern Sie die gespeicherte Antwort, um nur `web_search` anzuzeigen.

```bash theme={null}
echo "$NOIMOS_TOOLS_RESPONSE" | jq \
  '.data.tools[] | select(.name == "web_search") | {
    name,
    description,
    available,
    inputSchema,
    example,
    models,
    price
  }'
```

### 5. Vor Ausführung ein Angebot einholen

Senden Sie Toolnamen und Argumente, um Preisversion und maximalen Reservierungsbetrag zu erhalten. Dies startet keinen kostenpflichtigen Auftrag.

```bash theme={null}
NOIMOS_QUOTE_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/quote" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "tool": "web_search",
    "arguments": {
      "query": "content marketing trends",
      "count": 5
    }
  }')

echo "$NOIMOS_QUOTE_RESPONSE" | jq
```

Das Angebot liefert `priceVersion` und `maximumChargeMicros` für die Ausführung. Übernehmen Sie beide Werte unverändert; eine eigene Berechnung ist unnötig. `maximumChargeMicros` ist eine Ganzzahl in Millionsteln eines USD: 1 USD entspricht 1,000,000 micros.

```json theme={null}
{
  "data": {
    "tool": "web_search",
    "priceVersion": "...",
    "currency": "usd",
    "minimumChargeMicros": 0,
    "maximumChargeMicros": 0,
    "expiresAt": "..."
  }
}
```

Die obigen Beträge zeigen nur das Antwortformat. Im nächsten Schritt lesen Sie die tatsächlichen Werte aus der gespeicherten Antwort.

### 6. Angebotene Anfrage ausführen

Verwenden Sie dieselben Tools und Argumente wie im Angebot und ergänzen Sie Preisversion und maximalen Reservierungsbetrag. Fügen Sie einen Idempotenzschlüssel für diese logische Anfrage hinzu.

```bash theme={null}
export NOIMOS_PRICE_VERSION=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.priceVersion')
export NOIMOS_MAXIMUM_CHARGE_MICROS=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.maximumChargeMicros')
export NOIMOS_IDEMPOTENCY_KEY=$(uuidgen)

NOIMOS_EXECUTION_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/web_search" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NOIMOS_IDEMPOTENCY_KEY" \
  --data "$(jq -n \
    --arg priceVersion "$NOIMOS_PRICE_VERSION" \
    --argjson maximumChargeMicros "$NOIMOS_MAXIMUM_CHARGE_MICROS" \
    '{
      tool: "web_search",
      arguments: {
        query: "content marketing trends",
        count: 5
      },
      priceVersion: $priceVersion,
      maximumChargeMicros: $maximumChargeMicros
    }')")

echo "$NOIMOS_EXECUTION_RESPONSE" | jq
export NOIMOS_EXECUTION_ID=$(echo "$NOIMOS_EXECUTION_RESPONSE" | jq -r '.data.id')
```

Das Beispiel übernimmt das Angebot aus Schritt 5 und erzeugt mit `uuidgen` einen neuen Idempotenzschlüssel. Bei Annahme werden HTTP 202 und eine Ausführungs-ID zurückgegeben.

```json theme={null}
{
  "data": {
    "id": "EXECUTION_ID",
    "tool": "web_search",
    "status": "queued",
    "reservedMicros": 0,
    "chargedMicros": 0
  }
}
```

Die Antwort enthält außerdem Preisversion, Ausgabe, Fehler und Zeitangaben. `chargedMicros: 0` während der Verarbeitung bedeutet nicht, dass die Ausführung kostenlos abgerechnet wurde.

### 7. Ergebnis mit derselben Ausführungs-ID abfragen

Fragen Sie die in Schritt 6 gespeicherte ID bis zum Abschluss in Abständen von mindestens fünf Sekunden ab.

```bash theme={null}
while true; do
  NOIMOS_STATUS_RESPONSE=$(curl --fail-with-body \
    "$NOIMOS_PLATFORM_API_URL/tools/executions/$NOIMOS_EXECUTION_ID" \
    -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

  echo "$NOIMOS_STATUS_RESPONSE" | jq
  NOIMOS_STATUS=$(echo "$NOIMOS_STATUS_RESPONSE" | jq -r '.data.status')

  case "$NOIMOS_STATUS" in
    succeeded|failed|cancelled|needs_review) break ;;
  esac

  sleep 5
done
```

`queued`, `running` und `waiting` bedeuten laufende Verarbeitung. Bei `succeeded` lesen Sie `output` und `chargedMicros`. Weitere Status erläutert [Ausführung und Abrechnung verwalten](https://docs.noimosai.com/de/developers/api/execution-and-billing.md).

> [!WARNING]
>
> Ist die Antwort auf die Ausführung unbekannt, senden Sie nicht mit einem neuen Idempotenzschlüssel erneut. Derselbe Inhalt mit demselben Schlüssel liefert die bereits angenommene Ausführung.

## Weiterführende Seiten

Lesen Sie anschließend die für Ihre Implementierung relevanten Seiten:

* [Anfragen authentifizieren](https://docs.noimosai.com/de/developers/api/authentication.md): Schlüsselberechtigungen und Speicherung
* [Ausführung und Abrechnung verwalten](https://docs.noimosai.com/de/developers/api/execution-and-billing.md): lange Aufträge, Wiederholungen und Abrechnung
* [API-Referenz](https://docs.noimosai.com/de/developers/api/reference.md): Endpunkte, Status und Limits
* [Dokumentation](https://platform.noimosai.com/docs) der Developer Platform: aktuelle Beispiele


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