Qwen3.8-Max 文本生成

Qwen3.8-Max（qwen3.8-max）是阿里通义千问 2026 年 8 月 3 日发布的新一代旗舰，稀疏 MoE 架构、2.4 万亿总参数，支持 1M 上下文、131K 最大输出，原生接受文本、图片、视频三种输入。API易在发布当天上架，并完成了 586 次实测调用——本页的能力矩阵、参数行为与计费提醒全部来自实测，不是转述官方文档。

API易已接入 Qwen3.8-Max：模型名 qwen3.8-max。默认开启深度思考（默认 xhigh 档，思考 tokens 计入输出计费），日常对话建议显式设 reasoning_effort="none"，实测输出可从约 158 tokens 降到 5 tokens。上一代见 Qwen3.6 系列（历史版本）。

核心优势

比官网便宜 17.5％

输入 $1.65、输出 $4.95 每 1M tokens，阿里云官网为 $2/$6。可叠加充值活动继续下探。

1M 上下文实测可用

8K / 32K / 128K 三档正文，中部与尾部各埋一枚标识，两个端点 6/6 全部精确召回。128K 单次约 80 秒。

一个模型三种模态

文本、图片、视频输入全部实测通过，无需在「长文模型」和「视觉模型」之间切换。

Agent 能力大幅提升

FrontierSWE 由上代 40.7 升至 73.5，DeepSWE 21.6 → 56.6。工具调用链路完整，两轮 round-trip 实测通过。

端点支持

端点	状态	说明
`/v1/chat/completions`	✅ 完整可用	推荐主用。工具调用、结构化输出、多模态、流式全部实测通过
`/v1/messages`	⚠️ 代码集成可用	回传历史消息前需剥掉 `thinking` 块，见下方「Anthropic 端点用法」
`/v1/responses`	❌ 暂不支持	30 次测试全部失败，已反馈渠道方

模型定价

每 1M tokens，折扣前挂牌价：

项目	API易	阿里云官网	差价
输入	$1.65	$2.00	低 17.5％
输出（含思考）	$4.95	$6.00	低 17.5％
缓存读	$0.20625	$0.25	低 17.5％
缓存写	$2.0625	—	—

可叠加充值活动，实际成本更低。

技术规格

项目	参数
模型名	`qwen3.8-max`
架构	稀疏 MoE，2.4 万亿总参数
上下文窗口	1M tokens（非思考模式输入上限 991K，思考模式 983K）
最大输出	131,072 tokens（越界报错明确给出 `[1, 131072]`）
最大思考预算	262K tokens
思考模式	默认开启，默认档位 `xhigh`
输入模态	文本、图片、视频
输出速率	约 19–22 tokens/s（实测）
首字延迟	流式 TTFT 约 1.85 秒（实测 P50）

官方基准：GPQA Diamond 92.6、PaperBench 93.0、OmniDocBench 1.5 92.1、Terminal-Bench 2.1 86.6、OSWorld-Verified 86.1、IFBench 82.8、FrontierSWE 73.5、SWE-bench Pro 67.7。

思考控制（最重要的一节）

Qwen3.8-Max 默认就在思考，档位为 xhigh。思考 tokens 计入输出计费，且占比常达 90％以上。

`reasoning_effort` 七个值，四个真实档位

参数接受 7 个值，但实测只对应 4 个真实档位：

传入值	实际档位	实测思考量
`none`	关闭思考	0 tokens
`minimal` / `low`	低档	约 100 tokens
`medium`	中档	约 150 tokens
`high` / `xhigh` / `max`	默认档（三者等价）	约 150–175 tokens

传 max 不会比 xhigh 想得更多。传其他值会返回 400 并列出合法值。

关闭思考的写法

response = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "你好"}],
    reasoning_effort="none",
    max_tokens=500,
)

extra_body 里的 enable_thinking: false 与 chat_template_kwargs: {"enable_thinking": false} 同样生效，效果等价。

max_tokens 不约束思考 tokens。 实测设 max_tokens=1，仍被计 1054 个输出 token，其中 1045 个是思考。max_tokens 只截断可见回答。想控制成本请用 reasoning_effort，不要指望 max_tokens。

`thinking_budget` 不生效

传 128 / 512 / 4096 任何数值，实测行为都等同于 low 档，数值不起作用。请改用 reasoning_effort。

调用示例

Python（OpenAI SDK 兼容）

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-apiyi-key",
    base_url="https://api.apiyi.com/v1"
)

# 日常对话：关思考，快且省
resp = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "用一句话解释什么是负载均衡"}],
    reasoning_effort="none",
    max_tokens=500,
)
print(resp.choices[0].message.content)

# 复杂推理：保持默认思考档位
resp = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "证明：任意 5 个整数中必存在 3 个数之和被 3 整除"}],
    max_tokens=4000,
)
print(resp.choices[0].message.reasoning_content)  # 思考过程
print(resp.choices[0].message.content)            # 最终答案

图片输入

import base64

with open("chart.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "这张图上写的是什么数字？"},
        {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
    ]}],
    max_tokens=500,
)

远程图片 URL 在本端点同样可用，直接把 url 填成 https://... 即可。

视频输入

resp = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "这段视频里有什么？"},
        {"type": "video_url", "video_url": {"url": f"data:video/mp4;base64,{b64_video}"}},
    ]}],
    max_tokens=1000,
)

视频理解单次耗时实测 144–285 秒，请把客户端超时设到 300 秒以上，并优先用流式或异步任务队列承接。

另有帧序列写法 {"type": "video", "video": [帧1, 帧2, ...]}，要求 4–8000 帧，少于 4 帧会返回 400。

cURL

curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-apiyi-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [{"role": "user", "content": "你好"}],
    "reasoning_effort": "none"
  }'

工具调用

Chat Completions 端点的工具调用完整可用：单工具、并行多工具、两轮 round-trip、20 个工具中选 1、流式增量拼接、parallel_tool_calls: false 全部实测通过。

强制工具调用需同时关闭思考。 tool_choice 设为 "required" 或指定具体函数时，必须同时设 reasoning_effort="none"，否则返回 400（tool_choice does not support being set to required or object in thinking mode）或静默不调用。tool_choice 用 "auto" / "none" 不受此限制。同理，n > 1 也需要关闭思考。

resp = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "查一下北京天气"}],
    tools=tools,
    tool_choice={"type": "function", "function": {"name": "get_weather"}},
    reasoning_effort="none",   # 必须
)

结构化输出

response_format 的 json_schema 实测严格守约：嵌套对象、枚举、数组、additionalProperties: false 全部生效，无多余字段、无 Markdown 代码块包裹。

结构化场景请显式关思考。 同一个 schema 实测对比：

配置	输出 tokens	其中思考	耗时
`json_schema` + 默认思考	4,066	3,971	100 秒
`json_schema` + `reasoning_effort="none"`	154	0	4.7 秒

两者守约程度完全一致，成本和延迟差一个数量级。

上下文缓存

命中门槛约 1024 tokens：818 tokens 的前缀不命中，1070 tokens 起命中
真实多轮对话吃得到缓存：逐轮追加消息的场景每轮都命中
长文收益显著：128K 上下文实测缓存命中 98.6％，32K 命中 99.3％

缓存命中在实测中不够稳定，同样的前缀在不同轮次时有时无，TTL 无法从接口回显可靠推断。请把缓存收益当作「有则赚到」，不要拿它做成本预算。

Anthropic 端点用法

/v1/messages 可用于代码集成，但回传历史消息前需要剥掉 thinking 块，否则返回 400（if content is list. item must be dict and key[type] should in dict）。

def strip_thinking(blocks):
    return [b for b in blocks if b.get("type") != "thinking"]

messages.append({"role": "assistant", "content": strip_thinking(resp["content"])})

实测这样处理后，3 轮跨轮记忆、工具调用两轮 round-trip、工具结果进入后续记忆全部正常。

Claude Code 等现成客户端暂不可用——这类客户端默认原样回显历史 content blocks，无法改变其行为，第二轮就会 400。请改用 /v1/chat/completions。

该端点的其他差异：response_format 被静默忽略（结构化输出请改用工具强制）、tool_choice 只接受 OpenAI 格式、图片只支持 base64（远程 URL 返回 400）、reasoning_effort 不生效（关思考请用 thinking: {"type": "disabled"}）。

参数兼容性

参数	状态	说明
`temperature`	✅	有效范围 `[0.0, 2.0)`，传 2 即报 400
`top_p`	✅	有效范围 `(0.0, 1.0]`
`top_k` / `presence_penalty` / `frequency_penalty`	✅
`stop` / `stop_sequences`	✅	两端点均生效
`logprobs` / `top_logprobs`	✅
`stream` + `stream_options`	✅	流式始终回 usage，长流式完整终止无尾部扣留
`partial: true`	✅	前缀续写，续写时不思考
`n > 1`	⚠️	需同时设 `reasoning_effort="none"`
`seed`	❌	同 seed 两次输出不同，不保证确定性
`prefix: true`	❌	无效，请用 `partial: true`
`thinking_budget`	❌	数值不生效
内置联网搜索	❌	`enable_search` 与 `tools: [{"type": "web_search"}]` 均被静默丢弃

最佳实践

日常对话与高频调用

显式设 reasoning_effort="none"。实测耗时从约 5 秒降到 2 秒、输出 tokens 降到 1/30。

长文档与代码库分析

128K 召回实测精确，长文缓存命中率高。把大文档放在消息前部，追问放在尾部。

数据抽取

用 json_schema 约束结构，同时关思考。守约程度不受影响。

Agent 与工具编排

走 /v1/chat/completions。需要强制调用时记得关思考。

常见问题

为什么我设了 max_tokens 还是被扣了很多 token？

max_tokens 只约束可见回答，不约束思考部分。实测 max_tokens=1 仍被计 1054 个输出 token。控制成本请用 reasoning_effort="none"。

为什么 tool_choice 指定了函数却报 400？

思考模式下不支持 tool_choice 强制调用。请同时传 reasoning_effort="none"。

为什么 /v1/responses 调不通？

该端点对本模型暂未接入，30 次测试全部失败（错误码在 404 与 400 之间跳变）。已反馈渠道方，接通后会在实时动态公告。请改用 /v1/chat/completions。

Claude Code 能用这个模型吗？

暂时不能。/v1/messages 端点拒绝含 thinking 块的历史消息，而 Claude Code 默认原样回显。自己写代码调用时剥掉该块即可正常使用。

usage 里为什么有时没有 reasoning_tokens？

该模型背后有多条上游线路，其中一条不回显 reasoning_tokens 与 cached_tokens，实测约占 chat 请求的三分之一。已反馈渠道方统一口径。需要精确核算思考成本时请留意这一点。

视频调用为什么很慢？

视频理解单次实测 144–285 秒，属于模型本身的处理耗时。请把超时设到 300 秒以上，并考虑用异步队列承接。

产品基础

基础 API

图片 API（官转）

视频 API（官转）

多模态理解 API

文本生成

检索与安全

核心优势

比官网便宜 17.5％

1M 上下文实测可用

一个模型三种模态

Agent 能力大幅提升

端点支持

模型定价

技术规格

思考控制（最重要的一节）

`reasoning_effort` 七个值，四个真实档位

关闭思考的写法

`thinking_budget` 不生效

调用示例

Python（OpenAI SDK 兼容）

图片输入

视频输入

cURL

工具调用

结构化输出

上下文缓存

Anthropic 端点用法

参数兼容性

最佳实践

日常对话与高频调用

长文档与代码库分析

数据抽取

Agent 与工具编排

常见问题

相关文档

​核心优势

比官网便宜 17.5％

1M 上下文实测可用

一个模型三种模态

Agent 能力大幅提升

​端点支持

​模型定价

​技术规格

​思考控制（最重要的一节）

​reasoning_effort 七个值，四个真实档位

​关闭思考的写法

​thinking_budget 不生效

​调用示例

​Python（OpenAI SDK 兼容）

​图片输入

​视频输入

​cURL

​工具调用

​结构化输出

​上下文缓存

​Anthropic 端点用法

​参数兼容性

​最佳实践

日常对话与高频调用

长文档与代码库分析

数据抽取

Agent 与工具编排

​常见问题

​相关文档

核心优势

端点支持

模型定价

技术规格

思考控制（最重要的一节）

`reasoning_effort` 七个值，四个真实档位

关闭思考的写法

`thinking_budget` 不生效

调用示例

Python（OpenAI SDK 兼容）

图片输入

视频输入

cURL

工具调用

结构化输出

上下文缓存

Anthropic 端点用法

参数兼容性

最佳实践

常见问题

相关文档