跳到正文

建立對話補全

OpenAI 相容的 Chat Completions:GPT、Gemini、GLM、千問、DeepSeek、Grok、Claude 等對話模型共用此端點。

POST/v1/chat/completions

給定一組對話訊息,回傳模型的回覆。OpenAI SDK 只需把 Base URL 換成 https://api.hop-base.com/v1、換上對應分組的密鑰。

下表只列網關會檢查、改寫或拒絕的欄位,以及各模型頁寫明的取值;未列出的 OpenAI 欄位原樣轉發,取值範圍按模型官方規格。整個請求體上限 60 MB,超過回傳 413。

Claude 模型也可以用本端點(Claude 分組的密鑰),計費與 /v1/messages 完全一致。不傳 max_tokens 時非串流預設 16000、串流預設 64000,且不超過模型的輸出上限;Claude 模型不使用 temperature / top_p,傳了會被忽略、不報錯;n 大於 1、舊式 functions / function_call、音訊輸入回傳 400。多輪工具調用之間不回傳思考區塊,客戶端支援 Anthropic 協定時優先用 /v1/messages。/v1/responses 不支援 Claude 模型,回傳 404。

產生扣費的非串流回應會回傳本次實際扣費:回應標頭 X-HopBase-Cost / X-HopBase-Cost-USD / X-HopBase-Currency,以及回應主體根物件 usage 裡的 cost / cost_usd / currency(usage 原有欄位保留)。cost_usd 為本次從餘額實際扣除的美元金額,cost 為同一筆扣費的人民幣金額,currency 恆為 CNY。串流(SSE)不回傳,請到控制台「使用記錄」查看;未扣費的回應(如錯誤)不帶。詳見帳戶 API · 扣費。

請求標頭

Authorization:必填string

Bearer sk-…:主控台「API 密鑰」中建立的密鑰,所屬分組須包含請求的模型

請求主體參數JSON

模型
未列出的欄位原樣轉發。選擇模型系列,查看該系列文件寫明的取值與限制。
model:必填string

目前密鑰分組內的模型 ID,以 GET /v1/models 的回傳為準。分組不包含該模型時回傳 404 model_not_found;gpt-image-* 等圖片模型調本端點回傳 400 image models do not support Chat Completions, please use the Images API

messages:必填array of object

對話訊息。缺失回傳 400 missing messages field,空陣列回傳 400 messages must not be an empty array

數量≥ 1 項

max_tokens:選填integer

輸出上限。網關不截斷、不改寫;上限按模型官方規格,超出由模型回傳錯誤

max_completion_tokens:選填integer

同 max_tokens,OpenAI 新欄位名

stream:選填boolean

true 回傳 SSE,事件格式見串流事件

預設false

stream_options:選填object

串流選項

tools:選填array of object

函式工具,OpenAI function tools 格式,原樣轉發。

tool_choice:選填string 或 object

auto / none / required 或指定函式,原樣轉發

temperature:選填number

取樣溫度,原樣轉發,範圍按模型官方規格

top_p:選填number

核取樣,原樣轉發,範圍按模型官方規格

reasoning_effort:選填string

推理檔位。取值因模型而異,請在上方選擇模型種類檢視

service_tier:選填string

只保留 priority / flex;其他取值會被移除後再轉發,不報錯。priority 僅在所用分組支援時生效並按 Fast 價計費,不支援時按標準檔處理、按標準價計費;「GPT 官方直連(Azure)」分組不支援 priority

可選值priorityflex

回傳

200成功。非串流為 chat.completion JSON;stream: true 時為 SSE(text/event-stream)

回應標頭

X-HopBase-Cost:選填string

本次請求扣費的人民幣金額(與 X-HopBase-Cost-USD 為同一筆扣費),最多 6 位小數,如 0.0816。只在本次產生扣費時回傳;串流(SSE)不回傳;生圖耗時約 40 秒以上時回應標頭已提前送出,以回應主體 usage.cost 為準

X-HopBase-Cost-USD:選填string

本次請求實際從餘額扣除的美元金額,與使用記錄裡這一筆相同,最多 8 位小數,如 0.012;只隨 X-HopBase-Cost 一起回傳

X-HopBase-Currency:選填string

X-HopBase-Cost 的幣種,恆為 CNY

id:選填string

本次補全的 ID

object:選填"chat.completion"

固定為 chat.completion

created:選填integer

Unix 秒

model:選填string

實際使用的模型 ID

choices:選填array of object

候選回覆;多數模型只回傳 1 條

usage:選填object

Token 用量

錯誤

400請求體無法讀取、缺 messages 等
401沒帶密鑰、密鑰無效或已過期(missing_api_key / invalid_api_key / api_key_expired)
402餘額或密鑰 / 成員 / 部門額度用完(insufficient_quota)
404模型不在這把密鑰的分組裡(model_not_found),或路徑不屬於該分組(route_not_found)
413請求體超過 60 MB(request_too_large)
429帳戶或密鑰並行已達上限(user_concurrency_limit / apikey_concurrency_limit),帶 Retry-After

相關頁面