Erstellung von Chat-Bilderkennung (Streaming) Base64

Schnittstellenbeschreibung (API-Beschreibung): Bei Eingabe eines Prompts gibt das Modell eine oder mehrere vorhergesagte Vervollständigungen zurück und kann auch die Wahrscheinlichkeiten für alternative Tokens an jeder Position liefern. Diese API wird hauptsächlich verwendet, um Dialog-Vervollständigungen zu erstellen, die Bilderkennung (basierend auf Base64) und Text-Prompts kombinieren.

Offizielle Referenz: OpenAI API-Dokumentation

Schnittstellendetails

Anfragemethode: POST
Anfrage-URL: https://api.codingplanx.ai/v1/chat/completions
Datenformat: application/json

Anfrage-Header (Request Headers)

Parametername	Erforderlich	Typ	Beispielwert	Beschreibung
Content-Type	Ja	string	`application/json`	Datenformat
Accept	Ja	string	`application/json`	Empfangsformat
Authorization	Nein	string	`Bearer {{YOUR_API_KEY}}`	Authentifizierungs-Token

Anfrage-Parameter (Request Body)

Feldname	Typ	Erforderlich	Beschreibung
model	string	Ja	ID des zu verwendenden Modells (z. B.: `gpt-4o-mini`).
messages	array	Ja	Eine Liste der bisherigen Nachrichten im Dialog. Enthält `role` und `content`. Für die Bilderkennung kann `content` ein Array sein, das Text und `image_url` (Base64) enthält.
tools	array	Ja	Eine Liste von Tools, die das Modell aufrufen kann. Derzeit werden nur Funktionen als Tools unterstützt. Dient zur Bereitstellung einer Liste von Funktionen, für die das Modell JSON-Eingaben generieren kann.
tool_choice	object	Ja	Steuert, welche Funktion das Modell aufruft. `none` bedeutet, dass keine aufgerufen wird; `auto` bedeutet automatische Auswahl; es kann auch eine bestimmte Funktion erzwungen werden.
temperature	integer	Nein	Sampling-Temperatur, zwischen 0 und 2. Höhere Werte (wie 0.8) machen die Ausgabe zufälliger, niedrigere Werte (wie 0.2) machen sie deterministischer. Es wird empfohlen, dies nicht gleichzeitig mit `top_p` zu ändern.
top_p	integer	Nein	Nucleus-Sampling-Parameter. 0.1 bedeutet, dass nur die Tokens berücksichtigt werden, die die obersten 10 % der Wahrscheinlichkeitsmasse ausmachen. Es wird empfohlen, dies nicht gleichzeitig mit `temperature` zu ändern.
n	integer	Nein	Wie viele Chat-Vervollständigungsoptionen für jede Eingabenachricht generiert werden sollen. Standardwert ist 1.
stream	boolean	Nein	Schalter für Streaming-Ausgabe. Standardwert ist `false`. Wenn auf `true` gesetzt, werden partielle Nachrichten-Deltas als Server-Sent Events (SSE) gesendet und bei `data: [DONE]` beendet.
stop	string	Nein	Sequenzen (bis zu 4), bei denen die API die weitere Generierung von Tokens stoppt. Standardwert ist null.
max_tokens	integer	Nein	Die maximale Anzahl von Tokens, die in der Chat-Vervollständigung generiert werden sollen. Standardwert ist inf (unendlich).
presence_penalty	number	Nein	Präsenz-Strafe (-2.0 bis 2.0). Positive Werte bestrafen neue Tokens basierend darauf, ob sie bereits im Text vorkommen, was die Wahrscheinlichkeit erhöht, dass das Modell über neue Themen spricht.
frequency_penalty	number	Nein	Frequenz-Strafe (-2.0 bis 2.0). Positive Werte bestrafen neue Tokens basierend auf ihrer bisherigen Häufigkeit im Text, was die Wahrscheinlichkeit verringert, dass das Modell dieselben Inhalte wiederholt. Standardwert ist 0.
logit_bias	object	Nein	Modifiziert die Wahrscheinlichkeit, dass bestimmte Tokens in der Vervollständigung erscheinen. Akzeptiert ein JSON-Objekt, das Token-IDs auf Bias-Werte (-100 bis 100) abbildet.
user	string	Nein	Eine eindeutige Kennung für Ihren Endbenutzer, die hilft, Missbrauch zu überwachen und zu erkennen.
response_format	object	Nein	Gibt das Format an, das das Modell ausgeben muss. Die Übergabe von `{ "type": "json_object" }` aktiviert den JSON-Modus. Bei der Verwendung muss das Modell im Prompt explizit angewiesen werden, JSON auszugeben.
seen	integer	Nein	Beta-Funktion. Deterministischer Sampling-Seed. Wiederholte Anfragen mit demselben Seed und denselben Parametern sollten dieselben Ergebnisse liefern (absoluter Determinismus wird jedoch nicht garantiert).

Anfrage-Beispiel

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Was ist auf diesem Bild zu sehen? Bitte beschreibe es im Detail."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAiEAAAIhCAYAAACYF2qHAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAgAElEQVR4nOy9ebxtWVXf+x1zrrX2Pud2VRQUjUVf0glIYvOJLdJ8iCagIor... (Hier wird der überlange base64-String weggelassen)"
          }
        }
      ]
    }
  ]
}

Antwort-Parameter (Response Body)

Feldname	Typ	Beschreibung
id	string	Eindeutige Kennung der Chat-Vervollständigung.
object	string	Objekttyp, normalerweise `chat.completion` (oder `chat.completion.chunk` im Falle von Streaming).
created	integer	Unix-Zeitstempel der Erstellung.
choices	array	Liste der Vervollständigungsoptionen.
└─ index	integer	Index der Option in der Liste.
└─ message	object	Vom Modell generiertes Nachrichtenobjekt, enthält `role` und `content`.
└─ finish_reason	string	Grund, warum das Modell die Generierung gestoppt hat (z. B.: `stop` für normales Ende, `length` bei Erreichen des max_tokens-Limits).
usage	object	Statistiken zum Token-Verbrauch für diese Anfrage.
└─ prompt_tokens	integer	Anzahl der durch den Prompt verbrauchten Tokens (einschließlich der aus Bildern berechneten Tokens).
└─ completion_tokens	integer	Anzahl der durch den generierten Inhalt verbrauchten Tokens.
└─ total_tokens	integer	Gesamtanzahl der für diese Anfrage verbrauchten Tokens.

Antwort-Beispiel (Erfolgreich 200 OK)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

Häufig gestellte Fragen (FAQs)

Q1: Wie aktiviere ich die Streaming-Ausgabe (Streaming)? A: Setzen Sie den Parameter stream im Request Body auf true. Nach der Aktivierung wartet die Schnittstelle nicht mehr darauf, dass die gesamte Antwort generiert ist, sondern sendet Datenblöcke im Format data: {...} als Server-Sent Events (SSE) Wort für Wort bzw. Satz für Satz zurück, bis das Flag data: [DONE] das Ende der Generierung signalisiert.

Q2: Welche Anforderungen gibt es für die Base64-Codierung bei der Bilderkennung? A: Der Base64-String des Bildes muss das korrekte MIME-Type-Präfix enthalten, z. B. data:image/png;base64, oder data:image/jpeg;base64,. Es wird empfohlen, die Bildgröße vor der Konvertierung in Base64 angemessen zu komprimieren, um Netzwerkverzögerungen zu reduzieren und den Verbrauch von prompt_tokens zu senken (zu große Bilder verbrauchen viele Tokens oder können sogar das Kontextlimit überschreiten).

Q3: Warum wurde die Antwort des Modells abgeschnitten? A: Bitte überprüfen Sie den Wert von choices[0].finish_reason im Response Body. Wenn dieser length ist, bedeutet dies, dass der generierte Text das von Ihnen festgelegte Limit von max_tokens erreicht hat oder dass der gesamte Dialog das maximale Kontextfensterlimit des Modells überschritten hat. Sie können dieses Problem beheben, indem Sie den Wert für max_tokens erhöhen.

Q4: Wie zwinge ich das Modell, Daten im JSON-Format auszugeben? A: Zunächst müssen Sie im Request Body "response_format": { "type": "json_object" } setzen. Wichtiger Hinweis: Zusätzlich zum Setzen dieses Parameters müssen Sie das Modell im System-Prompt (system prompt) oder Benutzer-Prompt (user prompt) unter messages in natürlicher Sprache ausdrücklich anweisen, JSON auszugeben (z. B.: "Bitte gib das Ergebnis im JSON-Format aus"). Wenn Sie dies nicht tun, kann das Modell in einer Endlosschleife aus leeren Generierungen stecken bleiben, bis die Tokens erschöpft sind.

Q5: Was soll ich tun, wenn ein "401 Unauthorized"-Fehler auftritt? A: Bitte überprüfen Sie, ob der Parameter Authorization im Request-Header den API-Key korrekt enthält. Das Format muss strikt Bearer IHR_API_KEY lauten (beachten Sie das Leerzeichen zwischen Bearer und dem Key).