Gemeinsame Chat Completions | API-Dokumentation

# Common Chat Completions

Unified chat API for switching text models through the `model` parameter. The request format is compatible with OpenAI Chat Completions.

POST https://api.apihop.ai/v1/chat-completions

Unified chat API for switching text models through the `model` parameter. The request format is compatible with OpenAI Chat Completions.

Claude Sonnet 4.6 (`claude-sonnet-4-6`) is supported by the upstream supplier but is not currently published on RequestBeam. It is not an active integration default. Before calling any model, confirm access with your own `GET https://api.apihop.ai/v1/models` response.

This endpoint returns one complete JSON response by default. Set `stream: true` explicitly when you need SSE streaming.

```text
POST https://api.apihop.ai/v1/chat-completions
```

## Authentication

All requests require Bearer Token authentication.

```http
Authorization: Bearer YOUR_API_KEY
```

If authentication fails, check:

- Whether the API Key is correct
- Whether the key is valid for this API Base URL
- Whether the request header is spelled correctly
- Whether a proxy rewrites the authorization header

## Body

### `model` (string, required, Default: gpt-5.4)

Documented text model IDs (confirm access with `GET https://api.apihop.ai/v1/models`):

- OpenAI: `gpt-5.4`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-6-astra`
- Anthropic: `claude-fable-5`, `claude-fable-5-1`, `claude-opus-4-6`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-5`, `claude-sonnet-5-5`
- DeepSeek: `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-v4.1-flash`

(V4.1 Flash is a distinct model ID, available only after deployment and enablement; check `GET https://api.apihop.ai/v1/models`).

- Gemini: `gemini-3.6-flash`, `gemini-3.7-flash`, `gemini-3.8-flash`, `gemini-3.5-flash-lite`, `gemini-4-argon` (after deployment and enablement)
- Kimi: `kimi-k3`
- MiniMax: `minimax-m3`

See the [Model Catalog](https://apihop.ai/en/docs/api-reference/models) for the complete list and the models visible to the current API Key. Use your own `GET https://api.apihop.ai/v1/models` response as the current source of availability. See the [DeepSeek](https://apihop.ai/en/docs/api-reference/DeepSeek/models), [Gemini](https://apihop.ai/en/docs/api-reference/Gemini/models), [Kimi](https://apihop.ai/en/docs/api-reference/Kimi/models), and [MiniMax](https://apihop.ai/en/docs/api-reference/MiniMax/models) guides for family-specific selection notes and examples.

### `messages` (object[], required)

Chat messages. Each message should include:

- `role`: `system`, `user`, or `assistant`
- `content`: message content

Example:

```json
  [
    {"role": "system", "content": "You are a helpful Python tutor."},
    {"role": "user", "content": "How should I learn programming?"}
  ]
```

**Model-specific sampling limits:** `gpt-6-astra` does not accept legacy `temperature`, `top_p`, or `top_logprobs`; omit those fields even when an older client includes them. RequestBeam's GPT-6 Astra Playground also hides the legacy sampling and penalty controls. `claude-sonnet-5` rejected `top_p` in a documented integration recheck, so omit it for that model as well. Passing an optional field through a proxy does not establish that the selected upstream model supports it.

### `temperature` (number, Default: 1.0)

Sampling temperature. OpenAI-compatible clients commonly use `0` through `2`, but the selected model makes the final validation decision.

### `max_tokens` (integer)

Optional maximum output tokens, as a positive integer. Omit this field to use the upstream default for the selected model; defaults and maximum limits vary by model and upstream configuration.

Depending on the model, the budget may include reasoning tokens as well as final text. A small budget can cause `finish_reason: "length"`, truncate the answer, or be exhausted before final text. Increasing it may increase cost.

### `max_completion_tokens` (integer)

Optional compatibility alternative to `max_tokens`, with the same budget considerations. A model may accept only one of these fields, so start with a minimal body when switching models. Omit both to use the upstream default.

### `stream` (boolean, Default: false)

Whether to stream the response.

- `true`: return Server-Sent Events
- `false`: return one complete response

### `top_p` (number, Default: 1.0)

Nucleus sampling parameter. OpenAI-compatible clients commonly use `0` through `1`; the selected model performs final validation.

### `frequency_penalty` (number, Default: 0)

Frequency penalty. OpenAI-compatible clients commonly use `-2.0` through `2.0`; the selected model performs final validation.

### `presence_penalty` (number, Default: 0)

Presence penalty. OpenAI-compatible clients commonly use `-2.0` through `2.0`; the selected model performs final validation.

### `stop` (string | array)

A stop sequence or array of stop sequences. The selected model determines the accepted count and behavior.

### `n` (integer, Default: 1)

Number of responses to generate. Use a number such as `1`, not a quoted string.

## Model Parameter Differences

Current text models support minimal streaming and non-streaming Chat requests, but optional parameter acceptance and effects vary by the selected model and its compatibility implementation.

The latest recheck on 2026-09-26 accepted `claude-fable-5` with `temperature: 0` and returned text. The same recheck rejected `claude-sonnet-5` with `top_p: 0.9` with HTTP `400` and `top_p is deprecated`. Omit `top_p` for that model. Acceptance establishes neither an effect on sampling nor a guarantee for other models or later requests; do not assume that all sampling parameters are supported.

The OpenAI checks on 2026-09-26 accepted `stop` for `gpt-5.6-sol` and `gpt-5.6-terra`. Parameter acceptance can change with the upstream and does not prove that a stop sequence is effective.

Native OpenAI-compatible Chat forwarding preserves `top_p` and `stop` in the upstream request. A route that converts Chat to Responses preserves `top_p` but does not forward `stop`. Forwarding a field does not establish upstream support or its effect; neither field has a platform-wide guarantee across routes.

Start with a minimal request when switching models, then verify sampling, stop sequences, and advanced tool parameters separately. For stop sequences, inspect the actual text and stop reason, not only the HTTP status. HTTP 200 does not establish a sampling effect. Output budgets must cover both the model's thinking and its final text.

## Request Example

```json
{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Hello, introduce yourself briefly."
    }
  ],
  "stream": false
}
```

## Response

### `id` (string)

Unique response identifier.

### `object` (string)

Object type, usually `chat.completion` or `chat.completion.chunk` for streaming.

### `created` (integer)

Unix creation timestamp.

### `model` (string)

Model identifier returned in the response.

### `choices` (array)

Generated choices, including message content, index, and finish reason.

### `usage` (object)

Token usage statistics.

### Success Example

```json
{
  "id": "chatcmpl-9876543210",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I am an AI assistant that can help with writing, coding, and analysis."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 42,
    "total_tokens": 70
  }
}
```

## Error Response

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for the full code reference, protocol differences, and diagnostic steps.

Chat Completions HTTP errors use a flat JSON body, including upstream HTTP errors returned before an SSE stream starts. For example, HTTP `402` returns:

```json
{
  "code": 40000,
  "message": "Insufficient credit. Required: 30000, Available: 20000",
  "type": "api_error"
}
```

- `code`: numeric platform error code, separate from the HTTP status and not a string
- `message`: human-readable error description
- `type`: `api_error`
- `requestId`: optional request identifier for troubleshooting

| HTTP status | `code` | Meaning |
| --- | --- | --- |
| 400 | 10000 | Invalid request |
| 401 | 20000 | Missing or invalid authentication |
| 402 | 40000 | Insufficient credit |
| 403 | 20001 | Access denied or model unavailable to this key |
| 404 | 30000 | Model or resource not found |
| 409 | 30001 | Request conflict |
| 422 | 10001 | Validation error |
| 429 | 40001 | Rate limit exceeded |
| 500 | 50003 | Internal error |
| 502 | 50000 | Upstream provider error |
| 503 | 50001 | Service unavailable |
| 504 | 50002 | Gateway timeout |

Check the HTTP status first to determine whether the request succeeded, then compare the numeric `code` for application-specific handling. Do not compare `code` with strings such as `"400"`, assume it equals the HTTP status, or parse `message` as a stable error identifier. Missing or incorrectly typed `messages` are rejected with HTTP `400` and `code: 10000` before provider invocation.

This error format applies to Chat Completions HTTP responses, not errors within an already-started SSE stream or other API protocols. Model Catalog and native protocol endpoints have their own documented error formats.

Einheitliche Chat-API zum Wechseln von Textmodellen über den Parameter model. Das Anfrageformat ist mit OpenAI Chat Completions kompatibel.

Claude Sonnet 4.6 (claude-sonnet-4-6) wird vom vorgelagerten Anbieter unterstützt, ist aber derzeit nicht bei RequestBeam veröffentlicht. Es ist kein aktiver Integrationsstandard. Bestätigen Sie vor jedem Modellaufruf den Zugriff anhand Ihrer eigenen Antwort von GET https://api.apihop.ai/v1/models.

Dieser Endpunkt liefert standardmäßig eine vollständige JSON-Antwort. Setzen Sie stream: true ausdrücklich, wenn Sie SSE-Streaming benötigen.

text

POST https://api.apihop.ai/v1/chat-completions

Authentifizierung

Alle Anfragen erfordern Bearer-Token-Authentifizierung.

http

Authorization: Bearer YOUR_API_KEY

Falls die Authentifizierung fehlschlägt, prüfen Sie:

Ob der API-Schlüssel korrekt ist
Ob der Schlüssel für diese API-Basis-URL gültig ist
Ob der Anfrageheader richtig geschrieben ist
Ob ein Proxy den Autorisierungsheader umschreibt

Anfragekörper

modelstringerforderlichStandard: gpt-5.4

Dokumentierte Textmodell-IDs (Zugriff mit GET https://api.apihop.ai/v1/models bestätigen):

OpenAI: gpt-5.4, gpt-5.5, gpt-5.6-sol, gpt-5.6-terra, gpt-6-astra
Anthropic: claude-fable-5, claude-fable-5-1, claude-opus-4-6, claude-opus-4-7, claude-opus-4-8, claude-opus-5, claude-opus-5-5, claude-sonnet-5, claude-sonnet-5-5
DeepSeek: deepseek-v4-flash, deepseek-v4-pro, deepseek-v4.1-flash

(V4.1 Flash ist eine eigenständige Modell-ID und erst nach Bereitstellung und Aktivierung verfügbar; prüfen Sie GET https://api.apihop.ai/v1/models).

Gemini: gemini-3.6-flash, gemini-3.7-flash, gemini-3.8-flash, gemini-3.5-flash-lite, gemini-4-argon (nach Bereitstellung und Aktivierung)
Kimi: kimi-k3
MiniMax: minimax-m3

Die vollständige Liste und die für den aktuellen API-Schlüssel sichtbaren Modelle finden Sie im Modellkatalog. Verwenden Sie Ihre eigene Antwort von GET https://api.apihop.ai/v1/models als aktuelle Verfügbarkeitsquelle. Die Leitfäden zu DeepSeek, Gemini, Kimi und MiniMax enthalten familienspezifische Auswahlhinweise und Beispiele.

messagesobject[]erforderlich

Chatnachrichten. Jede Nachricht sollte Folgendes enthalten:

role: system, user oder assistant
content: Nachrichteninhalt

Beispiel:

json

  [
    {"role": "system", "content": "You are a helpful Python tutor."},
    {"role": "user", "content": "How should I learn programming?"}
  ]

Modellspezifische Sampling-Grenzen: gpt-6-astra akzeptiert die alten Felder temperature, top_p und top_logprobs nicht; lassen Sie sie weg, auch wenn ein älterer Client sie einschließt. Der GPT-6-Astra-Playground von RequestBeam blendet die alten Sampling- und Strafparameter ebenfalls aus. claude-sonnet-5 lehnte top_p in einer dokumentierten Integrationsnachprüfung ab; lassen Sie es auch bei diesem Modell weg. Das Durchreichen eines optionalen Feldes durch einen Proxy belegt keine Unterstützung durch das gewählte Anbietermodell.

temperaturenumberStandard: 1.0

Sampling-Temperatur. OpenAI-kompatible Clients verwenden häufig 0 bis 2; die endgültige Validierung trifft jedoch das gewählte Modell.

max_tokensinteger

Optionale maximale Ausgabetokens als positive Ganzzahl. Lassen Sie das Feld weg, um den Anbieterstandard des gewählten Modells zu verwenden; Standardwerte und Höchstgrenzen hängen von Modell und Anbieterkonfiguration ab.

Je nach Modell kann das Budget Denktokens und endgültigen Text umfassen. Ein kleines Budget kann finish_reason: "length" verursachen, die Antwort abschneiden oder vor dem endgültigen Text verbraucht sein. Eine Erhöhung kann die Kosten steigern.

max_completion_tokensinteger

Optionale Kompatibilitätsalternative zu max_tokens mit denselben Budgethinweisen. Ein Modell akzeptiert möglicherweise nur eines dieser Felder; beginnen Sie beim Modellwechsel mit einem minimalen Anfragekörper. Lassen Sie beide weg, um den Anbieterstandard zu verwenden.

streambooleanStandard: false

Ob die Antwort gestreamt wird.

true: Server-Sent Events zurückgeben
false: eine vollständige Antwort zurückgeben

top_pnumberStandard: 1.0

Nucleus-Sampling-Parameter. OpenAI-kompatible Clients verwenden häufig 0 bis 1; das gewählte Modell übernimmt die endgültige Validierung.

frequency_penaltynumberStandard: 0

Häufigkeitsstrafe. OpenAI-kompatible Clients verwenden häufig -2.0 bis 2.0; das gewählte Modell übernimmt die endgültige Validierung.

presence_penaltynumberStandard: 0

Präsenzstrafe. OpenAI-kompatible Clients verwenden häufig -2.0 bis 2.0; das gewählte Modell übernimmt die endgültige Validierung.

stopstring | array

Eine Stoppsequenz oder ein Array von Stoppsequenzen. Das gewählte Modell bestimmt die akzeptierte Anzahl und das Verhalten.

nintegerStandard: 1

Anzahl zu erzeugender Antworten. Verwenden Sie eine Zahl wie 1, keine Zeichenfolge in Anführungszeichen.

Unterschiede bei Modellparametern

Aktuelle Textmodelle unterstützen minimale Chat-Anfragen mit und ohne Streaming. Annahme und Auswirkungen optionaler Parameter hängen jedoch vom gewählten Modell und seiner Kompatibilitätsimplementierung ab.

Die jüngste Nachprüfung am 2026-09-26 akzeptierte claude-fable-5 mit temperature: 0 und lieferte Text. Dieselbe Prüfung lehnte claude-sonnet-5 mit top_p: 0.9 mit HTTP 400 und top_p is deprecated ab. Lassen Sie top_p für dieses Modell weg. Die Annahme belegt weder eine Sampling-Wirkung noch eine Garantie für andere Modelle oder spätere Anfragen; gehen Sie nicht davon aus, dass alle Sampling-Parameter unterstützt werden.

Die OpenAI-Prüfungen am 2026-09-26 akzeptierten stop für gpt-5.6-sol und gpt-5.6-terra. Die Parameterannahme kann sich beim Anbieter ändern und beweist nicht die Wirksamkeit einer Stoppsequenz.

Native OpenAI-kompatible Chat-Weiterleitung behält top_p und stop in der Anbieteranfrage bei. Eine Route, die Chat in Responses umwandelt, behält top_p bei, leitet stop jedoch nicht weiter. Das Weiterleiten belegt weder Anbieterunterstützung noch Wirkung; für keines der Felder gibt es eine plattformweite Garantie über alle Routen hinweg.

Beginnen Sie beim Modellwechsel mit einer minimalen Anfrage und prüfen Sie Sampling, Stoppsequenzen und erweiterte Werkzeugparameter getrennt. Prüfen Sie bei Stoppsequenzen den tatsächlichen Text und Stoppgrund, nicht nur den HTTP-Status. HTTP 200 belegt keine Sampling-Wirkung. Ausgabebudgets müssen Denkprozess und endgültigen Text des Modells abdecken.

Anfragebeispiel

json

{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Hello, introduce yourself briefly."
    }
  ],
  "stream": false
}

Antwort

idstring

Eindeutige Antwortkennung.

objectstring

Objekttyp, gewöhnlich chat.completion oder bei Streaming chat.completion.chunk.

createdinteger

Unix-Erstellungszeitstempel.

modelstring

In der Antwort zurückgegebene Modellkennung.

choicesarray

Erzeugte Auswahlmöglichkeiten einschließlich Nachrichteninhalt, Index und Abschlussgrund.

usageobject

Statistik der Tokennutzung.

Erfolgsbeispiel

json

{
  "id": "chatcmpl-9876543210",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I am an AI assistant that can help with writing, coding, and analysis."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 42,
    "total_tokens": 70
  }
}

Fehlerantwort

Die vollständige Codereferenz, Protokollunterschiede und Diagnoseschritte finden Sie unter Fehlercodes und Fehlerbehebung.

HTTP-Fehler von Chat Completions verwenden einen flachen JSON-Körper, auch Anbieter-HTTP-Fehler vor Beginn eines SSE-Streams. HTTP 402 liefert beispielsweise:

json

{
  "code": 40000,
  "message": "Insufficient credit. Required: 30000, Available: 20000",
  "type": "api_error"
}

code: numerischer Plattformfehlercode, getrennt vom HTTP-Status und keine Zeichenfolge
message: lesbare Fehlerbeschreibung
type: api_error
requestId: optionale Anfragekennung zur Fehlerbehebung

HTTP-Status	`code`	Bedeutung
400	10000	Ungültige Anfrage
401	20000	Fehlende oder ungültige Authentifizierung
402	40000	Unzureichendes Guthaben
403	20001	Zugriff verweigert oder Modell für diesen Schlüssel nicht verfügbar
404	30000	Modell oder Ressource nicht gefunden
409	30001	Anfragekonflikt
422	10001	Validierungsfehler
429	40001	Ratenlimit überschritten
500	50003	Interner Fehler
502	50000	Fehler des vorgelagerten Anbieters
503	50001	Dienst nicht verfügbar
504	50002	Gateway-Zeitüberschreitung

Prüfen Sie zuerst den HTTP-Status, um den Erfolg festzustellen, und vergleichen Sie anschließend den numerischen code für anwendungsspezifische Behandlung. Vergleichen Sie code nicht mit Zeichenfolgen wie "400", setzen Sie ihn nicht mit dem HTTP-Status gleich und verwenden Sie message nicht als stabile Fehlerkennung. Fehlende oder falsch typisierte messages werden vor dem Anbieteraufruf mit HTTP 400 und code: 10000 abgelehnt.

Dieses Fehlerformat gilt für Chat-Completions-HTTP-Antworten, nicht für Fehler in einem bereits gestarteten SSE-Stream oder anderen API-Protokollen. Modellkatalog und native Protokollendpunkte besitzen eigene dokumentierte Fehlerformate.