跳到正文
HopBase 文檔
登入控制台

通義千問

用 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages 呼叫通義千問 3.8 與 3.7 系列模型。

項目填寫值
Base URLhttps://api.hop-base.com/v1
對話POST /v1/chat/completions
ResponsesPOST /v1/responses
Anthropic MessagesPOST /v1/messages

用 Bearer 鑑權，模型 ID 以 GET /v1/models 返回的精確寫法為準。在 /v1/messages 上也可以用 x-api-key 請求標頭。

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": "用五條要點總結本季度的風險。"
    }]
  }'

模型

模型 ID上下文圖片與影片輸入
qwen3.8-max1M支援
qwen3.8-flash1M支援
qwen3.7-max1M僅文本
qwen3.7-plus1M支援
qwen3.7-flash1M支援

五個型號都是 1,000,000 Token 上下文，單次最多 131,072 輸出 Token。

五個型號都在「通義千問 3.8/3.7 系（阿里官方）」分組，一把密鑰全都能調。千問密鑰調不到其他系列，其他系列的密鑰也調不到千問；萬相與快樂馬影片模型分別在「萬相 3.0 官方直連」「快樂馬 1.1 官方直連」分組，各需單獨的密鑰。

端點與請求參數

POST /v1/chat/completions、POST /v1/responses 和 POST /v1/messages 五個模型都可用，串流均正常。Codex CLI 等只支援 Responses 的用戶端可以直連；Claude Code 也能直連，見 Claude Code 與 Anthropic Messages。都不需要 CC Switch 路由。

下表針對 POST /v1/chat/completions。網關只攔截空 messages；千問特有字段原樣透傳、不做校驗，其餘限制來自模型服務。

參數必填類型與限制預設值說明
model必填上表五個 ID 之一—精確匹配
messages必填非空陣列；圖片寬高須大於 10 像素—圖片、影片按上表
max_tokens選填整數，上限 131,072（官方上限）服務預設限制輸出長度
enable_thinking選填布林服務預設千問特有，透傳
thinking_budget選填整數服務預設不能與 reasoning_effort 同時設置
reasoning_effort選填low / high / max 實測可用服務預設不能與 thinking_budget 同時使用
enable_search選填布林服務預設千問特有，透傳
tools、tool_choice選填同 OpenAIauto思考模式下有限制，見下方
response_format選填JSON 模式，行為與官方接口一致純文本{"type": "json_object"} 返回 JSON
stream選填布林false為 true 時以 SSE 串流回傳
stream_options.include_usage選填布林false串流下要收到 usage 必須設 true
  • 缺失或空陣列的 messages 由網關返回 400。
  • thinking_budget 與 reasoning_effort 同時設置返回 400。
  • 思考模式下 tool_choice 不能設為 required 或指定函式，否則返回 400。
  • 用 response_format 時，提示詞裡也要要求輸出 JSON。
  • stream_options.include_usage 不影響計費。
  • /v1/responses 的內容分片只收 input_text、input_image、input_file，不收影片；需要影片輸入請走 Chat Completions。

qwen3.8-max 實測輸入上限 991,808 Token，超出返回（報錯原文取自生產記錄）：

400 Range of input length should be [1, 991808]

完整參數見 API 參考：Chat Completions，選擇通義千問模型種類查看。

網關會改動請求的一處

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

行為對請求的影響
previous_response_id存在則剔除
store固定為 false

請求會在多個賬號間負載均衡，某個賬號簽發的 ID 在另一個賬號上無效，所以 previous_response_id 會被剔除。每輪請發送完整 input。

Claude Code 與 Anthropic Messages

POST /v1/messages 接受標準的 Anthropic Messages 請求，五個模型都可用，請求直接交給模型自己的 Anthropic 相容介面，所以 Claude Code 和 Anthropic SDK 都能直連。SDK 的 Base URL 填 https://api.hop-base.com，不帶 /v1。

用 CC Switch 時，在控制台金鑰列的 ··· 選單裡選「匯入 CCS」，再選 Claude Code。匯入會自動填好模型；介面格式保持預設的 Anthropic，不需要本地路由。手動設定如下：

export ANTHROPIC_BASE_URL="https://api.hop-base.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-key"
export ANTHROPIC_MODEL="qwen3.8-max"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="qwen3.8-flash"
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=1000000
claude

Claude Code 不認得這些 ID，所以要用 CLAUDE_CODE_MAX_CONTEXT_TOKENS 告訴它真實的上下文窗口；不設的話，它會在 200K Token 時壓縮對話。更多選項見 Claude Code。

  • 思考在 thinking 區塊裡返回，計入 output_tokens。thinking: {"type": "disabled"} 可以關閉思考。
  • qwen3.7-max 只支援文字，帶圖請求在到達模型之前就回傳 400；另外四個模型都能看圖。
  • 強制呼叫工具（tool_choice 設為 any 或指定工具）需要關閉思考。開著思考時，qwen3.8-max、qwen3.8-flash、qwen3.7-plus 回傳 400；qwen3.7-max 與 qwen3.7-flash 無論是否思考都會忽略強制，可能直接用文字回答。
  • max_tokens 超過 131,072 時，三個 3.7 模型回傳 400，3.8 模型不拒絕。
  • cache_control 斷點會在送出前移除，所以不支援顯式緩存；自動前綴緩存照常生效。2026-10-03 實測，Claude Code 從第二輪起有 89%–97% 的 prompt 命中緩存。
  • Claude Code 每次請求都帶著很長的系統提示詞和工具列表，實測在你的第一條訊息之前就有約 15,000 Token。閾值較低的模型（如 qwen3.7-flash）在 Claude Code 對話裡很早就會越過分檔閾值，見下一節。
400 Range of max_tokens should be [1, 131072]
400 Model qwen3.7-max does not accept image input. Remove the image from the request, including earlier turns of the conversation, or use a model that supports images.
400 The tool_choice parameter does not support being set to required or object in thinking mode

用 Anthropic Messages 對賬時，input_tokens 不含緩存命中部分，對應用量記錄的「輸入 Token」；cache_read_input_tokens 對應「緩存輸入 Token」。

計費與用量

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

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

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

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

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

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

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

錯誤處理

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

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

下一步

本頁目錄

模型端點與請求參數網關會改動請求的一處Claude Code 與 Anthropic Messages計費與用量錯誤處理下一步