Chat Completions API-Dokumentation (Chat-Vervollständigungen)

Diese API generiert basierend auf einer bereitgestellten Liste von Dialognachrichten eine oder mehrere vorhergesagte Antworten (Completions) des Modells. Sie unterstützt Streaming-Ausgaben, Werkzeugaufrufe (Function Calling) sowie die Anpassung verschiedener Sampling-Parameter.

1. Schnittstelleninformationen (API-Info)

API-Name: Offizieller N-Test
HTTP-Methode: POST
Endpunkt-URL: https://api.codingplanx.ai/v1/chat/completions
Content-Type: application/json
Authentifizierung: Bearer {{YOUR_API_KEY}}

2. Header (Request Headers)

Parameter	Erforderlich	Typ	Beschreibung	Beispiel
Content-Type	Ja	string	Medientyp-Kennung	`application/json`
Accept	Ja	string	Vom Client akzeptiertes Antwortformat	`application/json`
Authorization	Nein	string	API-Zugriffstoken (Access Token)	`Bearer sk-xxxxxx`

3. Anfragekörper (Request Body)

Parameter	Erforderlich	Typ	Beschreibung
model	Ja	string	Zu verwendende Modell-ID (z. B. `gpt-4o`, `gpt-3.5-turbo`).
messages	Ja	array	Liste der Dialognachrichten. Jedes Objekt enthält eine `role` (system/user/assistant) und `content`.
tools	Ja	array	Liste der Werkzeuge, die das Modell aufrufen kann. Derzeit werden nur Funktionen unterstützt.
tool_choice	Ja	object	Steuert, welche Funktion das Modell aufruft. `none` (kein Aufruf), `auto` (automatisch) oder die Angabe einer spezifischen Funktion.
temperature	Nein	number	Sampling-Temperatur (0-2). Höhere Werte machen die Ausgabe zufälliger, niedrigere Werte deterministischer. Es wird empfohlen, entweder diesen Wert oder `top_p` anzupassen, nicht beide.
top_p	Nein	number	Nucleus-Sampling. 0.1 bedeutet, dass nur Tokens berücksichtigt werden, die die obersten 10 % der Wahrscheinlichkeitsmasse ausmachen.
n	Nein	integer	Standardwert ist 1. Anzahl der zu generierenden Antwortoptionen pro Eingabenachricht.
stream	Nein	boolean	Standardwert ist false. Wenn true, werden inkrementelle Tokens gesendet (ähnlich wie bei ChatGPT).
stop	Nein	string	Stopp-Sequenz. Wenn das Modell auf diese Zeichen trifft, wird die Generierung abgebrochen.
max_tokens	Nein	integer	Maximale Anzahl der zu generierenden Tokens. Standard ist unendlich (inf).
presence_penalty	Nein	number	Wert zwischen -2.0 und 2.0. Bestraft bereits erwähnte Themen und erhöht die Wahrscheinlichkeit, dass das Modell über neue Themen spricht.
frequency_penalty	Nein	number	Wert zwischen -2.0 und 2.0. Bestraft häufig wiederholte Wörter.
logit_bias	Nein	object	Verändert die Wahrscheinlichkeit, dass bestimmte Tokens generiert werden.
user	Nein	string	Eindeutige Kennung des Endnutzers, dient zur Erkennung von Missbrauch.
response_format	Nein	object	Legt das Antwortformat fest. Beispiel: `{ "type": "json_object" }` aktiviert den JSON-Modus.
seen	Nein	integer	Funktion in der Testphase. Legt einen Seed fest, um eine deterministische Ausgabe zu erzielen.

4. Antwortparameter (Response Body)

Parameter	Typ	Beschreibung
id	string	Eindeutige Kennung für diese Anfrage.
object	string	Objekttyp, in der Regel `chat.completion`.
created	integer	Zeitstempel der Erstellung der Anfrage (in Sekunden).
choices	array	Liste der Antwortoptionen.
├─ index	integer	Der Index dieser Option in der Liste.
├─ message	object	Die vom Modell generierte spezifische Nachricht.
│ ├─ role	string	Rolle, in der Regel `assistant`.
│ └─ content	string	Textinhalt der Nachricht.
└─ finish_reason	string	Grund für den Stopp der Generierung (z. B. `stop`, `length`, `tool_calls`).
usage	object	Übersicht des Token-Verbrauchs.
├─ prompt_tokens	integer	Für die Eingabe (Prompt) verbrauchte Tokens.
├─ completion_tokens	integer	Für die Ausgabe (Generierung) verbrauchte Tokens.
└─ total_tokens	integer	Gesamtverbrauch an Tokens.

5. Beispiele (Examples)

Request-Beispiel

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "who are u?"
        }
    ],
    "n": 1,
    "max_tokens": 100,
    "temperature": 0.8,
    "stream": false
}

Response-Beispiel

{
    "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
    }
}

6. Häufig gestellte Fragen (FAQs)

F: Warum erhalte ich einen Fehler, wenn ich response_format: { "type": "json_object" } festlege? A: Bei der Verwendung des JSON-Modus müssen Sie das Modell in den messages über eine System- oder Benutzernachricht ausdrücklich anweisen, JSON zu generieren (z. B. "Bitte antworte im JSON-Format"). Andernfalls könnte das Modell hängen bleiben oder einen Fehler ausgeben, da es kein gültiges JSON-Objekt generieren kann.

F: Können temperature und top_p gleichzeitig angepasst werden? A: Technisch ist das möglich, aber offiziell wird empfohlen, nur einen der beiden Parameter anzupassen. Die Anpassung eines Wertes reicht in der Regel aus, um die Zufälligkeit der Ausgabe zu steuern. Eine gleichzeitige Änderung beider Parameter kann zu schwer vorhersehbaren Ergebnissen führen.

F: Wie empfange ich Daten, wenn stream: true aktiviert ist? A: Wenn Streaming aktiviert ist, sendet der Server eine Reihe von Server-Sent Events (SSE). Der Datenteil jedes Ereignisses ist ein JSON-Objekt, und der Stream endet mit data: [DONE]. Sie müssen eine Streaming-Parsing-Bibliothek (wie z. B. response.iter_lines() in Python) verwenden, um die Daten Zeile für Zeile zu verarbeiten.

F: Wie wird der Token-Verbrauch berechnet? A: Im Englischen entspricht 1 Token etwa 4 Zeichen oder 0,75 Wörtern. Bei chinesischen Texten kann ein Schriftzeichen 1-2 Tokens beanspruchen. Der tatsächliche Endverbrauch richtet sich ausschließlich nach dem Feld usage im Response Body.

F: Was bedeutet finish_reason: "length"? A: Dies bedeutet, dass der generierte Inhalt das von Ihnen festgelegte max_tokens-Limit überschritten hat oder die maximale Kontextlänge des Modells erreicht wurde, was dazu führte, dass der Text abgeschnitten wurde.

F: Unterstützt die API Funktionsaufrufe (Function Calling)? A: Ja. Wenn Sie Funktionsprototypen über den Parameter tools definieren, kann das Modell je nach Bedarf tool_calls anstelle des normalen content im Feld choices[0].message zurückgeben.