Nutzung mit cURL

NWS Managed AI Models lassen Sich in eigenen Anwendungen nutzen, bspw. über die verfügbare API. Diese funktioniert sehr ähnlich wie ein Chat. Dem Modell wird eine Liste von Nachrichten geschickt, und es antwortet darauf auf Basis des gegebenen Kontexts. Die Anfragen sind abei zustandslos, das Modell "erinnert" sich nicht an Gespräche; stattdessen wird der bisherige Gesprächsverlauf bei jeder Anfrage erneut übermittelt.

So kann man:

• Rollen wie system, user und assistant verwenden, um Verhalten und Kontext zu steuern
• Mit Parametern wie temperature oder top_p die Kreativität und Vielfalt beeinflussen
• Über max_tokens und andere Optionen die Antwortlänge und Struktur kontrollieren

Am Beispiel von cURL sind im Folgenden Beispiele zur Interaktion mit der API der NWS Managed AI Models gegeben.

Grundaufbau einer Anfrage

Eine einfache Anfrage mit cURL an die API inkl. Antwort des Modells sieht wie folgt aus:

curl https://api.ai.nws.netways.de/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
        "model": "openai/gpt-oss-120b",
        "messages": [
            {"role": "system", "content": "Du bist ein freundlicher Assistent."},
            {"role": "user",   "content": "Wie kocht man ein perfektes Risotto?"}
        ],
        "max_tokens": 2000,
        "temperature": 0.8
    }'

Payload der Anfrage

Der wichtigste Teil der Anfrage ist der sog. Payload, also das JSON-Objekt im -d Parameter. Es beschreibt, wie das Modell antworten soll, und enthält den eigentlichen Prompt.

{
    "model": "openai/gpt-oss-120b",
    "messages": [...],
    "max_tokens": 2000,
    "temperature": 0.8
}

Messages

Das Feld messages im Payload der Anfrage ist eine Auflistung von Nachrichten. Jede Nachricht besteht aus zwei Feldern:

• role: definiert, wer spricht
• content: der eigentliche Text

[
    {"role": "system", "content": "Du bist ein freundlicher Assistent."},
    {"role": "user",   "content": "Wie kocht man ein perfektes Risotto?"}
]

Rollen im Überblick

• system: legt das Verhalten und den Stil des Modells fest (z.B. „Du bist ein Koch“).
• user: die Eingabe (Prompt) des Nutzers.
• assistant: Antworten des Modells.

Weitere wichtige Parameter

Verfügbare Antwortformate

Erweiterte Nutzung

Das folgende Beispiel zeigt, wie man mit der Chat-Completions API mehrere Gesprächsrunden, kreative Steuerung und Wiederholungs-Kontrolle realisiert.

Mehrere Chat-Turns (Kontext aufbauen)

Die messages Liste enthält den bisherigen Verlauf des Gesprächs. Dadurch kann das Modell Kontext behalten und folgende Fragen im Zusammenhang verstehen.

Das Modell "merkt" sich nichts. Es ist zustandslos und sieht nur das, was man ihm in messages mitgibt. Kontext entsteht allein dadurch, dass der bisherige Verlauf explizit in der Anfrage mitgeschickt wird.

curl https://api.ai.nws.netways.de/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
    "model": "openai/gpt-oss-120b",
    "messages": [
        {"role": "system", "content": "Du bist ein freundlicher Kochassistent."},
        {"role": "user", "content": "Wie koche ich ein Risotto?"},
        {"role": "assistant", "content": "Zuerst Zwiebeln anschwitzen und glasig werden lassen."},
        {"role": "user", "content": "Wie verhindere ich, dass es anbrennt?"}
    ]
}'

Antwortvielfalt steuern (temperature, top_p, n)

Diese Parameter bestimmen, wie kreativ oder vielfältig die Antwort ist.

curl https://api.ai.nws.netways.de/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
    "model": "openai/gpt-oss-120b",
    "messages": [{"role": "user", "content": "Gib mir einen Risotto-Tipp"}],
    "temperature": 0.8,
    "top_p": 0.9,
    "n": 2,
    "response_format": { "type": "json_object" }
}'

Das Modell gibt zwei leicht unterschiedliche Tipps zurück, z. B. eine klassische und eine kreative Variante.

Wiederholungen kontrollieren (presence_penalty, frequency_penalty)

Diese beiden Parameter helfen, redundante oder sich wiederholende Antworten zu vermeiden.

curl https://api.ai.nws.netways.de/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
    "model": "openai/gpt-oss-120b",
    "messages": [{"role": "user", "content": "Erkläre kurz, wie man Risotto macht"}],
    "presence_penalty": 0.6,
    "frequency_penalty": 0.4,
    "response_format": { "type": "json_object" }
}'

Dadurch klingen Antworten meist natürlicher und weniger „stotternd“.

curl https://api.ai.nws.netways.de/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
    "model": "openai/gpt-oss-120b",
    "messages": [
        {"role": "system", "content": "Du bist ein strukturierter Kochassistent."},
        {"role": "user", "content": "Wie koche ich Risotto?"},
        {"role": "assistant", "content": "Zwiebeln anbraten, Reis glasig werden lassen."},
        {"role": "user", "content": "Wie verhindere ich, dass es anbrennt?"}
    ],
    "temperature": 0.8,
    "max_tokens": 300, 
    "top_p": 0.9,
    "n": 1,
    "presence_penalty": 0.6,
    "frequency_penalty": 0.4
}'

Beispielausgabe:

{
  "id": "chatcmpl-b3efd1d34405223b",
  "object": "chat.completion",
  "created": 1765531885,
  "model": "openai/gpt-oss-120b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "**Risotto ohne Anbrennen zubereiten – Schritt‑für‑Schritt‑Tipps**\n\n| Problem | Ursache | Lösung (Kurz & Lang) |\n|--------|----------|----------------------|\n| **Rohes Anbrennen am Topfboden** | Zu hohe Hitze + zu wenig Flüssigkeit | 1️⃣ **Mittlere bis niedrige Temperatur** wählen. 2️⃣ Immer genug Brühe im Topf haben ...",
        "refusal": null,
        "annotations": null,
        "audio": null,
        "function_call": null,
        "tool_calls": [],
        "reasoning": "We need to respond in German, as user is speaking German. Provide advice on preventing risotto from burning: constant stirring, proper heat, using heavy-bottomed pan, adding broth gradually, not letting it sit too long, deglazing, etc. Also give tips on temperature control and equipment. Should be structured.",
        "reasoning_content": "We need to respond in German, as user is speaking German. Provide advice on preventing risotto from burning: constant stirring, proper heat, using heavy-bottomed pan, adding broth gradually, not letting it sit too long, deglazing, etc. Also give tips on temperature control and equipment. Should be structured."
      },
      "logprobs": null,
      "finish_reason": "stop",
      "stop_reason": null,
      "token_ids": null
    }
  ],
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "prompt_tokens": 121,
    "total_tokens": 1347,
    "completion_tokens": 1226,
    "prompt_tokens_details": null
  },
  "prompt_logprobs": null,
  "prompt_token_ids": null,
  "kv_transfer_params": null
}