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 端點用法

引數相容性

最佳實踐

常見問題

相關文件