Chat Completions mit cURL über mehrere KI-Modelle hinweg

Sie können in einem einzigen Terminalbefehl mehr über ein AI-Gateway erfahren als aus einer langen Feature-Liste. Wenn das Gateway wirklich OpenAI-kompatibel ist, sollte dieselbe curl-Anfrage über unterstützte Modellfamilien hinweg funktionieren, während Basis-URL, Authorization-Header, Nachrichtenformat und Antwortverarbeitung stabil bleiben.

Dieses Tutorial zeigt das praktische Muster mit Flatkey: Beginnen Sie mit einer einzigen Chat-Completions-Anfrage, verschieben Sie den Modellnamen in eine Variable und testen Sie mehrere aktuelle Modellfamilien, ohne die Integration neu zu schreiben. Es richtet sich an Entwickler, die eine API zuerst im Terminal validieren möchten, bevor sie ein SDK hinzufügen oder Anwendungscode einchecken.

Hinweis zur Modellauswahl: Modellkataloge ändern sich. Die unten aufgeführten Modell-IDs entsprechen der öffentlichen Dokumentation von Flatkey, geprüft am 24. Juli 2026. Bestätigen Sie die aktuelle Modellzeile und Verfügbarkeit, bevor Sie eine ID in der Produktion verwenden.

The shortest working chat-completions cURL request

Erstellen Sie einen Flatkey-API-Schlüssel, exportieren Sie ihn in Ihrer Shell und senden Sie eine Anfrage an den OpenAI-kompatiblen Chat-Completions-Endpunkt:

export FLATKEY_API_KEY="your-flatkey-api-key"

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Write a one-sentence product description for a waterproof daypack."
      }
    ]
  }'

Vier Teile sind wichtig:

Für kompatible Chat-Modelle ist das wichtigste Feld, das Sie ändern, model.

Use the same cURL shape across model families

Platzieren Sie die Modell-ID in einer Shell-Variable, damit sich der Request-Body nicht ändern muss:

export FLATKEY_API_KEY="your-flatkey-api-key"
export MODEL="gpt-4o-mini"

curl -sS https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL\",
    \"messages\": [
      {
        \"role\": \"system\",
        \"content\": \"Return concise ecommerce copy.\"
      },
      {
        \"role\": \"user\",
        \"content\": \"Write a product title for a lightweight waterproof daypack.\"
      }
    ],
    \"temperature\": 0.2
  }" | jq -r '.choices[0].message.content'

Führen Sie den Befehl nun erneut mit einer anderen dokumentierten Modell-ID aus:

export MODEL="claude-sonnet-4-6"

export MODEL="gemini-2.5-flash"

export MODEL="deepseek-v3.1"

Die Anfrage verwendet weiterhin denselben Endpunkt, dieselben Header, Nachrichten und denselben jq-Parser. Diese stabile Aufrufstruktur ist der betriebliche Vorteil: Sie können unterstützte Modellfamilien vergleichen, ohne für jeden Anbieter ein separates Terminal-Skript zu pflegen.

Hinweis zur Modellauswahl: Eine gemeinsame Anfragestruktur bedeutet nicht, dass sich jedes Modell identisch verhält. Unterstützte Parameter, Kontextgrenzen, Tool-Verhalten, Sicherheitsverhalten, Latenz und Ausgabestil können sich unterscheiden. Behandeln Sie Kompatibilität als einfachere Integrationsoberfläche, nicht als Beweis dafür, dass Modelle austauschbar sind.

Führen Sie eine kleine Multi-Model-Testschleife aus

Für einen schnellen Vergleich im Terminal definieren Sie eine kurze Liste und senden Sie dieselbe Eingabeaufforderung an jedes Modell:

#!/usr/bin/env bash
set -euo pipefail

: "${FLATKEY_API_KEY:?Set FLATKEY_API_KEY first}"

MODELS=(
  "gpt-4o-mini"
  "claude-sonnet-4-6"
  "gemini-2.5-flash"
  "deepseek-v3.1"
)

PROMPT="Write three benefit-led bullet points for a waterproof commuter backpack."

for MODEL in "${MODELS[@]}"; do
  echo
  echo "=== $MODEL ==="

  jq -n \
    --arg model "$MODEL" \
    --arg prompt "$PROMPT" \
    '{
      model: $model,
      messages: [
        {role: "system", content: "You write concise ecommerce copy."},
        {role: "user", content: $prompt}
      ],
      temperature: 0.2
    }' |
  curl -sS https://router.flatkey.ai/v1/chat/completions \
    -H "Authorization: Bearer $FLATKEY_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @- |
  jq -r '.choices[0].message.content // .error.message'
done

Die Verwendung von jq -n zum Erzeugen von JSON ist sicherer, als einen langen Shell-String manuell zu escapen. Außerdem lässt sich das Skript so leichter mit Variablen, zusätzlichen Nachrichten oder optionalen Parametern erweitern.

Speichern Sie das Skript als compare-models.sh, machen Sie es ausführbar und führen Sie es aus:

chmod +x compare-models.sh
./compare-models.sh

Worauf Sie in der Ausgabe achten sollten

Ein Multi-Model-Test ist nur dann sinnvoll, wenn die Eingabeaufforderung und die Bewertungsmethode konsistent sind. Vergleichen Sie für eine Aufgabe mit E-Commerce-Texten:

Fügen Sie cURL-Zeitfelder hinzu, wenn Latenz wichtig ist:

curl -sS -o response.json \
  -w 'status=%{http_code} total=%{time_total}s\n' \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Schreibe einen Produkt-Slogan mit fünf Wörtern."}
    ]
  }'

jq . response.json

Dies trennt Transportmessungen von der Modellausgabe. Das Terminal gibt den HTTP-Status und die gesamte Anfragezeit aus, während die JSON-Antwort zur Prüfung verfügbar bleibt.

Hinweis zur Modellauswahl: Wählen Sie ein Produktionsmodell nicht anhand einer einzelnen Antwort aus. Führen Sie einen repräsentativen Satz von Prompts aus, wiederholen Sie die Anfragen und bewerten Sie die Ausgaben anhand der Anforderungen, die für Ihre Anwendung wichtig sind.

Halten Sie die Anfrage vergleichbar

Schon kleine Änderungen am Prompt oder an Parametern können einen Modelltest irreführend machen. Verwenden Sie diese Kontrollen:

1. Halten Sie die Nachrichten identisch. Verbessern Sie den Prompt nicht für ein Modell, aber nicht für die anderen.
2. Verwenden Sie dieselbe Temperatur. Niedrigere Werte machen Vergleichsläufe in der Regel leichter überprüfbar.
3. Erfassen Sie rohes JSON. Speichern Sie die vollständige Antwort, nicht nur den gerenderten Text.
4. Protokollieren Sie die Modell-ID. Ein Anzeigename ist für reproduzierbare Tests nicht präzise genug.
5. Trennen Sie Fehler von schlechten Antworten. Ein Transport- oder Verfügbarkeitsfehler ist keine Bewertung der Ausgabequalität.
6. Prüfen Sie die aktuelle Verfügbarkeit. Ein dokumentiertes Modell kann dennoch einen sich ändernden Betriebsstatus haben.

Ein grundlegendes Fehlerhandling hinzufügen

Verwenden Sie --fail-with-body, damit cURL bei HTTP-Fehlern beendet wird, während der Antwortkörper erhalten bleibt:

HTTP_BODY=$(mktemp)

if ! curl --fail-with-body -sS \
  -o "$HTTP_BODY" \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Gib das Wort bereit zurück."}
    ]
  }'; then
  jq -r '.error.message // "Anfrage fehlgeschlagen"' "$HTTP_BODY" >&2
  rm -f "$HTTP_BODY"
  exit 1
fi

jq -r '.choices[0].message.content' "$HTTP_BODY"
rm -f "$HTTP_BODY"

Fügen Sie in Anwendungscode außerdem explizite Timeouts, begrenzte Wiederholungsversuche für wiederholbare Fehler sowie Logging hinzu, das keine geheimen Schlüssel oder sensiblen Prompt-Inhalte preisgibt.

Eine praktische Richtlinie zur Modellauswahl

Die einfachste Richtlinie ist, nach Arbeitslast statt nach Anbietername auszuwählen:

Beginnen Sie mit dem kleinsten Modell, das Ihre Qualitätsgrenze zuverlässig erfüllt. Steigen Sie auf ein stärkeres Modell um, wenn die Aufgabe es erfordert. Wenn Sie Fallback-Routing hinzufügen, testen Sie den Fallback mit demselben Antwortvertrag, statt anzunehmen, dass er das Primärmodell ohne Änderungen an der Anwendung ersetzen kann.

Sie können den aktuellen Modellzugang und die Preise auf Flatkeys Preisseite prüfen, bevor Sie die IDs für einen Produktionstest auswählen.

Wann man von cURL zu einem SDK wechseln sollte

cURL ist ideal, um schnell vier Dinge zu bestätigen:

• der API-Schlüssel funktioniert
• die Basis-URL korrekt ist
• das ausgewählte Modell die Anfrage akzeptiert
• die Antwortstruktur zu Ihrem Parser passt

Wechseln Sie zu einem SDK, wenn Sie Streaming-Helpers, strukturierte Retry-Logik, typisierte Antworten, wiederverwendbare Clients oder Observability auf Anwendungsebene benötigen. Bewahren Sie die erfolgreiche cURL-Anfrage in Ihrem Runbook auf: Sie bleibt der schnellste Weg, Zugriffsprobleme am Gateway von Problemen mit der SDK-Konfiguration zu unterscheiden.

Abschließende Implementierungs-Checkliste

• Exportieren Sie den API-Schlüssel, statt ihn direkt in Skripte einzutragen.
• Verwenden Sie https://router.flatkey.ai/v1 als Basis-URL.
• Senden Sie kompatible Chat-Anfragen an /chat/completions.
• Verschieben Sie die Modell-ID in die Konfiguration.
• Erstellen Sie JSON mit jq, wenn das Escaping in der Shell komplex wird.
• Erfassen Sie HTTP-Status, Latenz, Antwortinhalt und Nutzungsdaten.
• Vergleichen Sie Modelle mit identischen Prompts und Parametern.
• Überprüfen Sie die aktuelle Katalogverfügbarkeit vor dem Produktionsrollout.
• Fügen Sie in Anwendungscode Timeouts, begrenzte Retries und secretsicheres Logging hinzu.

Eine stabile cURL-Anfrage gibt Ihnen einen sauberen Ausgangspunkt. Sobald sie funktioniert, verwandelt das Ändern des model-Felds diese Anfrage in ein praktisches Test-Harness für mehrere KI-Modellfamilien – ohne dass Sie Authentifizierung, Basis-URL oder Response-Parser jedes Mal ändern müssen.

Häufig gestellte Fragen

Kann ich dieselbe Chat-Completions-cURL-Anfrage für jedes KI-Modell verwenden?

Verwenden Sie sie für Modelle, die Flatkey über die kompatible Chat-Completions-Route bereitstellt. Andere Modalitäten oder protokollspezifische Funktionen können andere Endpunkte oder Anfragefelder erfordern.

Was ist der minimale Feldsatz für eine Chat-Completions-Anfrage?

Für eine grundlegende Anfrage geben Sie ein unterstütztes model und ein messages-Array an. Sie benötigen außerdem den Bearer-Authorization-Header und den JSON-Inhaltstyp.

Warum den Modellnamen in eine Umgebungsvariable setzen?

Es hält die Anfragestruktur stabil, reduziert Bearbeitungsfehler und macht Skripte leichter zwischen Staging-, Evaluierungs- und Produktionskonfigurationen auszuführen.

Sollte ich cURL in der Produktion verwenden?

cURL ist hervorragend für Verifizierung, Skripte und Runbooks geeignet. Die meisten Produktionsanwendungen profitieren von einem SDK oder HTTP-Client mit expliziter Unterstützung für Timeouts, Retries, Telemetrie und Typbehandlung.

Wie wähle ich zwischen GPT-, Claude-, Gemini- und DeepSeek-Modellen?

Treffen Sie die Auswahl mit einem repräsentativen Evaluationsdatensatz. Vergleichen Sie die Befolgung von Anweisungen, die Ausgabequalität, Latenz, Token-Nutzung, Fehlverhalten und die spezifischen Funktionen, die Ihre Arbeitslast erfordert. Bestätigen Sie vor der Einführung die aktuelle Verfügbarkeit.