Wenn Sie zum ersten Mal mit einer KI-API arbeiten, kann der Begriff „JSON 请求体" (JSON Request Body) zunächst einschüchternd wirken. Keine Sorge – dieser Leitfaden erklärt Ihnen alles von Grund auf, Schritt für Schritt.

Was ist ein „请求体" (Request Body)?

Bevor wir uns den Code ansehen, klären wir die Grundlagen. Stellen Sie sich eine API wie einen Briefkasten vor:

Der Request Body ist genau dieser „Brief" – er enthält alle Informationen, die die KI benötigt, um Ihre Frage zu beantworten.

Screenshot-Hinweis: In Ihrem API-Testing-Tool (z.B. Postman oder Insomnia) sehen Sie den Request Body im mittleren Bereich des Bildschirms, oft in einem Textfeld mit der Bezeichnung „Body" oder „Request Body".

Die Grundstruktur eines JSON Request Body

Ein typischer Request Body für eine KI-Konversation sieht so aus:

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "user",
      "content": "Hallo, wie geht es dir?"
    }
  ]
}

Diese drei Teile sind Pflichtfelder und bilden das Herzstück jeder API-Anfrage.

messages – Das Gesprächsprotokoll

Das messages-Feld ist ein Array (eine Liste) von Gesprächsbeiträgen. Es enthält die gesamte Unterhaltung mit der KI, einschließlich:

Warum ist das wichtig? Die KI „erinnert" sich nur an das, was im messages-Array steht. Wenn Sie also eine längere Konversation führen möchten, müssen Sie alle vorherigen Nachrichten mitsenden.

Screenshot-Hinweis: Im JSON-Editor erscheint messages als eckige Klammern [...] und enthält mehrere Objekte, die durch Kommas getrennt sind.

role – Wer spricht?

Das role-Feld gibt an, wer die jeweilige Nachricht verfasst hat. Es gibt drei Standard-Werte:

{
  "messages": [
    {
      "role": "system",
      "content": "Du bist ein freundlicher Deutschlehrer."
    },
    {
      "role": "user", 
      "content": "Wie sagt man 'Hello' auf Deutsch?"
    },
    {
      "role": "assistant",
      "content": "Hallo! Das Wort 'Hello' bedeutet auf Deutsch 'Hallo'."
    },
    {
      "role": "user",
      "content": "Danke! Was bedeutet 'Goodbye'?"
    }
  ]
}

Durch die Verwendung verschiedener role-Werte kann die KI den Kontext verstehen und kohärente Antworten geben.

content – Was wird gesagt?

Das content-Feld enthält den eigentlichen Text – Ihre Frage, die Anweisung oder die KI-Antwort. Es ist immer ein String (Text in Anführungszeichen).

Ein wichtiger Hinweis: Der gesamte content-Text zusammen mit den role-Bezeichnungen wird als „Kontext" bezeichnet. Je mehr Kontext Sie senden, desto besser versteht die KI Ihre Situation – aber desto mehr Tokens verbrauchen Sie auch.

Vollständiges Beispiel mit HolySheep AI

Jetzt sehen wir, wie eine vollständige API-Anfrage mit HolySheep AI aussieht:

import requests

url = "https://api.holysheep.ai/v1/chat/completions"
headers = {
    "Authorization": "Bearer YOUR_HOLYSHEEP_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "model": "gpt-4",
    "messages": [
        {
            "role": "system",
            "content": "Du bist ein hilfreicher Assistent."
        },
        {
            "role": "user",
            "content": "Erkläre mir JSON in einfachen Worten."
        }
    ],
    "temperature": 0.7,
    "max_tokens": 500
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Und so senden Sie mehrere Nachrichten für eine fortlaufende Konversation:

import requests

url = "https://api.holysheep.ai/v1/chat/completions"
headers = {
    "Authorization": "Bearer YOUR_HOLYSHEEP_API_KEY",
    "Content-Type": "application/json"
}


Komplette Konversationshistorie mitsenden

payload = {
    "model": "gpt-4",
    "messages": [
        {"role": "user", "content": "Was ist Python?"},
        {"role": "assistant", "content": "Python ist eine Programmiersprache."},
        {"role": "user", "content": "Ist sie einfach zu lernen?"},
        {"role": "assistant", "content": "Ja, Python gilt als einsteigerfreundlich."},
        {"role": "user", "content": "Wo wird sie verwendet?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Wichtige Parameter im Request Body

Neben den Pflichtfeldern können Sie weitere Parameter hinzufügen:

Warum HolySheep AI wählen?

Wenn Sie mit APIs arbeiten, zählt jeder Cent. HolySheep AI bietet unschlagbare Vorteile:

Im Vergleich: DeepSeek V3.2 kostet bei HolySheep nur $0.42 pro Million Tokens, während vergleichbare Modelle bei anderen Anbietern $8 oder mehr kosten.

Häufige Fehler und Lösungen

1. Fehler: „401 Unauthorized" oder „Invalid API Key"

Problem: Ihr API-Key ist falsch, abgelaufen oder nicht korrekt eingetragen.
Lösung: Überprüfen Sie Ihren Key in Ihrem HolySheep-Dashboard. Stellen Sie sicher, dass er exakt so eingegeben ist, einschließlich aller Zeichen. Entfernen Sie keine Leerzeichen am Anfang oder Ende.

2. Fehler: „400 Bad Request" – „messages is required"

Problem: Das messages-Feld fehlt komplett im Request Body.
Lösung: Fügen Sie das messages-Array hinzu. Auch wenn Sie keine Konversation führen möchten, muss das Array mindestens eine Nachricht vom Role „user" enthalten.

3. Fehler: „429 Rate Limit Exceeded"

Problem: Sie haben zu viele Anfragen in kurzer Zeit gesendet.
Lösung: Warten Sie einige Sekunden, bevor Sie erneut senden. Implementieren Sie in Ihrer Anwendung Wartezeiten zwischen den Anfragen. Bei HolySheep AI sind die Limits großzügig bemessen.

4. Fehler: „500 Internal Server Error"

Problem: Der Server hatte ein technisches Problem.
Lösung: Warten Sie einen Moment und versuchen Sie es erneut. Bei anhaltenden Problemen kontaktieren Sie den HolySheep-Support. Solche Fehler sind selten und werden meist schnell behoben.

5. Fehler: Leere oder abgeschnittene Antworten

Problem: Die KI-Antwort ist unvollständig oder endet abrupt.
Lösung: Erhöhen Sie den max_tokens-Wert. Prüfen Sie auch, ob die max_tokens-Einstellung nicht zu niedrig für Ihre Anfrage ist.

Zusammenfassung

Ein JSON Request Body für KI-APIs besteht aus:

Mit diesem Wissen können Sie Ihre ersten erfolgreichen API-Anfragen starten. Denken Sie daran: Übung macht den Meister. Beginnen Sie mit einfachen Anfragen und erweitern Sie schrittweise.

👉 Registrieren Sie sich bei HolySheep AI — Startguthaben inklusive

Verwandte Ressourcen

Verwandte Artikel