通義千問

通過 HopBase 的 OpenAI 兼容 Chat Completions 接口調用通義千問 3.8 與 3.7 系模型。

通義千問走 HopBase 的 OpenAI 兼容協議。使用 https://api.hop-base.com/v1,鑑權頭為 Authorization: Bearer sk-your-key,模型 ID 以 GET /v1/models 返回的精確寫法為準。

模型

模型 ID	上下文	圖片與視頻輸入
`qwen3.8-max`	1M	支持
`qwen3.8-flash`	1M	支持
`qwen3.7-max`	1M	僅文本
`qwen3.7-plus`	1M	支持
`qwen3.7-flash`	1M	支持

五個型號都是 1,048,576 Token 上下文,單次最多 991,808 輸入 Token 與 131,072 輸出 Token。五個同屬一個套餐分組,一把密鑰全都能調。

端點

POST /v1/chat/completions 是支持的入口,流式正常可用。

流式要拿 usage 得顯式訂閱

客戶端需要從流式響應裡讀 Token 用量時,請傳 stream_options: { "include_usage": true }。不傳也不影響計費準確性,只是那個 usage 塊不會下發給客戶端。

千問特有的請求字段,例如 enable_thinking、thinking_budget、enable_search,會原樣透傳給模型——HopBase 既不要求也不校驗它們。函數調用與 JSON 模式的行為與官方接口一致。

網關會改動請求的兩處

在千問上做長跑 Agent 之前,這兩條要先知道。

行為	對請求的影響
消息歷史守衛	`chat/completions` 上,消息超過 26 條時只保留開頭最多 2 條 `system` / `developer` 消息,加上最後 24 條,中間的會被丟棄
`previous_response_id`	存在則剔除。請求會在多個賬號間負載均衡,某個賬號簽發的 ID 在另一個賬號上無效

歷史守衛對 1M 上下文模型同樣生效

長多輪會話是按消息條數截斷的,不是按 Token 數。如果你的 Agent 依賴完整歷史,請自己把歷史壓縮進更少的消息裡,並把必須保留的內容放在前兩條 system 消息中。

長輸入請求

部分千問模型在單次請求的輸入長度跨過閾值後會升檔。

閾值看的是整個 prompt,緩存命中的部分與未命中的部分都算在內。
一旦跨過,整筆請求都按該檔結算,不是隻有超出閾值的那部分。
緩存幫不了你躲開閾值。緩存隻影響命中部分適用哪個單價,不會讓 prompt 在判檔時變短。想留在低檔,只能真的把單次輸入寫短。

哪些型號有階梯、閾值在哪,以登錄後的模型廣場為準。

讀 usage

completion_tokens 已經包含推理 Token,不要再加一遍。completion_tokens_details.reasoning_tokens 是輸出的子集,只用於展示。

HopBase 的用量記錄與響應體對輸入的口徑不同,對賬時要注意:

字段	含義
響應體 `prompt_tokens`	整個 prompt,含緩存命中部分
用量記錄輸入 Token	prompt 減去緩存命中部分
用量記錄緩存輸入 Token	緩存命中的那部分,單列

也就是說,用量記錄裡的輸入加緩存輸入,等於響應體的 prompt_tokens。

curl

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [{ "role": "user", "content": "用五條要點總結本季度的風險。" }]
  }'

錯誤處理

上游的 4xx 會透傳給你,但廠商專有的錯誤碼前綴會被剝掉,所以 message 文本可讀但不穩定。分支邏輯請基於 HTTP 狀態碼與 code 字段,不要匹配 message 字符串。

分組裡沒有的模型名返回 404 model_not_found。模型 ID 是精確匹配,請從 GET /v1/models 讀取,不要猜。

分組

通義千問有獨立的套餐分組。千問密鑰調不到其他系列,其他系列的密鑰也調不到千問。萬相 3.0 與快樂馬視頻模型雖然同屬一家廠商,但也是另一個分組、另一把密鑰。

本頁目錄