通用聊天補全 | API 文件

# 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.

透過 model 參數切換文字模型的統一聊天 API。請求格式相容於 OpenAI Chat Completions。

上游供應商支援 Claude Sonnet 4.6（claude-sonnet-4-6），但目前尚未在 RequestBeam 發布，因此不是已啟用的預設整合模型。呼叫任何模型前，請以您自己的 GET https://api.apihop.ai/v1/models 回應確認存取權限。

此端點預設傳回一個完整 JSON 回應。需要 SSE 串流時，請明確設定 stream: true。

text

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

驗證

所有請求均需要 Bearer Token 驗證。

http

Authorization: Bearer YOUR_API_KEY

若驗證失敗，請檢查：

API 金鑰是否正確
金鑰是否適用於此 API 基礎網址
請求標頭拼寫是否正確
代理是否改寫授權標頭

請求主體

modelstring必填預設: gpt-5.4

文件列出的文字模型 ID（請透過 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 是獨立模型 ID，僅在部署並啟用後可用；請檢查 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 (部署並啟用後)
Kimi: kimi-k3
MiniMax: minimax-m3

完整清單及目前 API 金鑰可見的模型，請見模型目錄。以您自己的 GET https://api.apihop.ai/v1/models 回應作為目前可用性的依據。各模型系列的選擇說明與範例，請見 DeepSeek、Gemini、Kimi 與 MiniMax 指南。

messagesobject[]必填

聊天訊息。每則訊息應包含：

role：system、user 或 assistant
content：訊息內容

範例：

json

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

模型特定的取樣限制： gpt-6-astra 不接受舊的 temperature、top_p 或 top_logprobs；即使舊版客戶端包含這些欄位，也請省略。RequestBeam 的 GPT-6 Astra Playground 也會隱藏舊取樣與懲罰控制。claude-sonnet-5 在有紀錄的整合複測中拒絕 top_p，因此該模型也請省略此欄位。代理轉送選填欄位不代表所選上游模型支援它。

temperaturenumber預設: 1.0

取樣溫度。OpenAI 相容客戶端通常使用 0 至 2，但最終驗證由所選模型決定。

max_tokensinteger

選填的最大輸出 token，必須為正整數。省略此欄位會使用所選模型的上游預設值；預設值與上限依模型及上游設定而異。

依模型而定，預算可能同時包含推理 token 與最終文字。預算過小可能造成 finish_reason: "length"、答案截斷，或在產生最終文字前耗盡。提高預算可能增加費用。

max_completion_tokensinteger

max_tokens 的選填相容替代欄位，適用相同預算注意事項。模型可能僅接受其中一個欄位，切換模型時請從最小請求主體開始。兩者均省略時使用上游預設值。

streamboolean預設: false

是否串流回應。

true：傳回 Server-Sent Events
false：傳回完整回應

top_pnumber預設: 1.0

核心取樣參數。OpenAI 相容客戶端通常使用 0 至 1，最終由所選模型驗證。

frequency_penaltynumber預設: 0

頻率懲罰。OpenAI 相容客戶端通常使用 -2.0 至 2.0，最終由所選模型驗證。

presence_penaltynumber預設: 0

存在懲罰。OpenAI 相容客戶端通常使用 -2.0 至 2.0，最終由所選模型驗證。

stopstring | array

停止序列或停止序列陣列。接受的數量及行為由所選模型決定。

ninteger預設: 1

要生成的回應數量。請使用像 1 這樣的數字，而非加引號的字串。

模型參數差異

目前的文字模型支援最小的串流與非串流 Chat 請求，但選填參數是否接受及其效果，取決於所選模型與其相容實作。

2026-09-26 的最近一次複測接受 claude-fable-5 搭配 temperature: 0，並傳回文字。同次複測中，claude-sonnet-5 搭配 top_p: 0.9 被拒絕，回傳 HTTP 400 與 top_p is deprecated。請為此模型省略 top_p。接受參數既不代表有取樣效果，也不保證其他模型或之後請求可用；請勿假設所有取樣參數都受支援。

2026-09-26 的 OpenAI 檢查接受 gpt-5.6-sol 與 gpt-5.6-terra 的 stop。參數接受情況可能隨上游變動，且不代表停止序列有效。

原生 OpenAI 相容 Chat 轉送會在上游請求中保留 top_p 與 stop。將 Chat 轉換為 Responses 的路由會保留 top_p，但不轉送 stop。轉送欄位不代表上游支援或有實際效果；兩個欄位都沒有跨所有路由的平台通用保證。

切換模型時從最小請求開始，再分別驗證取樣、停止序列與進階工具參數。對停止序列，請檢查實際文字與停止原因，不要只看 HTTP 狀態。HTTP 200 不代表存在取樣效果。輸出預算必須涵蓋模型思考與最終文字。

請求範例

json

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

回應

idstring

回應的唯一識別碼。

objectstring

物件類型，通常為 chat.completion，串流時為 chat.completion.chunk。

createdinteger

Unix 建立時間戳記。

modelstring

回應中傳回的模型識別碼。

choicesarray

生成的選項，包含訊息內容、索引與完成原因。

usageobject

Token 用量統計。

成功範例

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

錯誤回應

完整代碼參考、協定差異及診斷步驟，請見錯誤代碼與疑難排解。

Chat Completions 的 HTTP 錯誤使用扁平 JSON 主體，也包含 SSE 串流開始前傳回的上游 HTTP 錯誤。例如 HTTP 402 會傳回：

json

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

code：數字平台錯誤代碼，與 HTTP 狀態分開，且不是字串
message：人類可讀的錯誤說明
type：api_error
requestId：選填的請求識別碼，用於疑難排解

HTTP 狀態	`code`	意義
400	10000	請求無效
401	20000	缺少驗證或驗證無效
402	40000	餘額不足
403	20001	拒絕存取或此金鑰無法使用模型
404	30000	找不到模型或資源
409	30001	請求衝突
422	10001	驗證錯誤
429	40001	超過速率限制
500	50003	內部錯誤
502	50000	上游供應商錯誤
503	50001	服務不可用
504	50002	閘道逾時

先檢查 HTTP 狀態判斷請求是否成功，再比較數字 code 進行應用程式特定處理。請勿將 code 與 "400" 等字串比較、假設它等於 HTTP 狀態，或將 message 解析為穩定錯誤識別碼。缺少或類型錯誤的 messages 會在呼叫供應商前以 HTTP 400 與 code: 10000 拒絕。

此錯誤格式適用於 Chat Completions HTTP 回應，不適用於已開始的 SSE 串流內錯誤或其他 API 協定。模型目錄與原生協定端點各有文件記載的錯誤格式。