跳到正文
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计费与用量错误处理下一步