> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Qwen4-Max 旗艦多模態模型推薦｜APIYI

> Qwen4-Max（qwen4-max）支援原生視覺、工具呼叫與約 1M 上下文。APIYI 掛牌輸入 $1.50、輸出 $4.50、快取讀 $0.075 / 1M tokens，含 325 次實測結論與呼叫示例。

Qwen4-Max（`qwen4-max`）是阿里通義千問 Qwen4 系列的旗艦模型，採用 2.4 萬億引數骨幹架構，原生支援文本、圖片和影片輸入，面向複雜推理、程式設計 Agent、長文件分析與專業工作流。APIYI 已上架該模型，價格與海外版官網對齊，並完成 **325 次上架前實測**與 **15 次 Default 分組線上驗收**。

> [!NOTE]
>
> **模型名：`qwen4-max`**。公開分組為 Default、SVIP、CodexResponses、ClaudeCode，開放 Chat Completions、Responses、Messages 三端點。預設開啟思考；日常對話建議顯式設定 `reasoning_effort="none"`，減少思考 token 消耗。

## 核心優勢

> [card] 官網同價，可加贈
>
> 輸入 \$1.50、輸出 \$4.50、快取讀 \$0.075 / 1M tokens。疊加[充值階梯加贈](https://docs.apiyi.com/zh-Hant/faq/recharge-promotions.md) 10％–20％，等效約 83–91 折。

> [card] 近 1M 上下文實測
>
> 實際輸入 951,498 tokens，中部與尾部標識均準確召回，單次耗時 92.3 秒。介面返回的輸入上限為 991,808 tokens。

> [card] 原生多模態輸入
>
> 文本、圖片、影片均已實測。三端點圖片 OCR 與雙圖識別通過；Chat 影片理解可正確描述測試素材。

> [card] 完整 Agent 工具鏈
>
> 單工具、並行工具、強制與具名工具、流式增量及兩輪工具結果回傳均通過實測。

## 端點與分組

| 端點 | 開放狀態與分組建議 |
| - | - |
| `/v1/chat/completions` | 已開放；通用呼叫推薦 Default、SVIP |
| `/v1/responses` | 已開放；Codex / Responses 客戶端推薦 CodexResponses |
| `/v1/messages` | 已開放；Claude Code 客戶端推薦 ClaudeCode |
| 可用分組 | Default、SVIP、CodexResponses、ClaudeCode |
| 計費型別 | 按量付費 - Chat |

三端點均已開放，上表是按客戶端選擇分組的建議，並非對其他分組的呼叫限制。Default 分組令牌的 Responses、Messages 最小線上請求也已通過；實際可用分組以控制台令牌配置為準。

## 模型定價

每 1M tokens，折扣前掛牌價：

| 專案 | APIYI | 海外版官網 |
| - | -: | -: |
| 輸入 | **\$1.50** | \$1.50 |
| 輸出（含思考） | **\$4.50** | \$4.50 |
| 快取讀取 | **\$0.075** | \$0.075 |

價格與海外版 Qwen4-Max 官網對齊，可能調整，以頂部[「模型價格」](https://docs.apiyi.com/zh-Hant/models/index.md)欄目為準。充值活動採用餘額加贈，等效折扣約 83–91 折，詳見[充值優惠活動](https://docs.apiyi.com/zh-Hant/faq/recharge-promotions.md)。

## 技術規格與實測

| 專案 | 引數或實測結果 |
| - | - |
| 模型 ID | `qwen4-max` |
| 架構 | Qwen4 稀疏 MoE；2.4T 骨幹引數、每 token 啟用 71B，另有 328B N-gram Embedding 引數 |
| 上下文 | 官方標稱 1M；實測輸入 951,498 tokens 成功 |
| 輸入上限錯誤口徑 | `Range of input length should be [1, 991808]` |
| 輸入模態 | 文本、圖片、影片 |
| 思考控制 | 預設開啟；`none` / `off` 可關閉 |
| Chat 非流式耗時 | P50 5.65 秒，P95 8.16 秒 |
| Chat 流式首 token | P50 3.93 秒 |
| Chat 輸出速率 | P50 14.93 tokens/s |
| Chat 12 併發 | 12/12 成功，牆鍾 10.9 秒 |

上述效能和長上下文資料來自 2026-11-17 (UTC+8) 的上架前測試視窗，不作為長期 SLA。

## 思考控制與輸出預算

`reasoning_effort` 支援 `none`、`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。非法值會返回 400 並列出合法值。

* `none` / `off`：關閉思考，適合日常對話、資料抽取和高頻呼叫。
* `minimal` / `low` / `medium`：保留一定推理量；簡單任務上各檔差異不一定單調。
* `high` / `xhigh` / `max`：實測思考量更高，適合複雜推理與長程任務。
* `reasoning_effort` 與 `thinking_budget` 不可同時傳入，同傳返回 400。

```python theme={null}
resp = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": "用一句話解釋什麼是負載均衡"}],
    reasoning_effort="none",
    max_tokens=500,
)
```

> [!WARNING]
>
> **Qwen4-Max 的 `max_tokens` 會覆蓋思考與可見輸出的總預算。** 較小的上限可能全部耗在思考上，得到 HTTP 200 但正文為空，終止原因為 `length`。需要控制成本時使用 `reasoning_effort`；需要完整答案時同時給足 `max_tokens`。

## 呼叫示例

### Python（OpenAI SDK 相容）

```python theme={null}
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="qwen4-max",
    messages=[
        {"role": "user", "content": "證明：任意 5 個整數中必存在 3 個數之和被 3 整除"}
    ],
    reasoning_effort="xhigh",
    max_tokens=4000,
)

print(resp.choices[0].message.content)
```

### 圖片輸入

```python theme={null}
import base64

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

resp = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "讀取圖中的數字，只返回數字。"},
        {"type": "image_url", "image_url": {
            "url": f"data:image/png;base64,{image_b64}"
        }},
    ]}],
    max_tokens=500,
)
```

base64 與遠端圖片 URL 均已通過原廠渠道測試。影片可使用 `video_url` 的 base64 data URL，或 `{"type": "video", "video": [...]}` 幀序列；幀序列要求 4–80 幀。

### cURL

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

## 工具呼叫

Chat Completions 的單工具、並行工具、`parallel_tool_calls=false`、`tool_choice="required"`、具名工具、禁止工具、流式工具增量及完整兩輪 round-trip 均已通過上架前實測。

```python theme={null}
resp = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": "查一下北京天氣"}],
    tools=tools,
    tool_choice={"type": "function", "function": {"name": "get_weather"}},
    max_tokens=1000,
)
```

需要多個候選答案時，`n > 1` 應與 `reasoning_effort="none"` 同用；思考開啟時 `n > 1` 返回 400。

## 結構化輸出

`response_format={"type": "json_schema"}` 的巢狀物件、陣列、列舉和 `additionalProperties: false` 均通過實測，流式輸出也能得到合法 JSON。

> [!TIP]
>
> 嚴格資料抽取優先使用 `json_schema`，並設定 `reasoning_effort="none"`。普通 `json_object` 只保證返回可解析 JSON，實測仍可能返回頂層陣列，不能代替 Schema 約束。

## 上下文快取

* 約 170 tokens 的短字首未命中；更長的固定字首可觀察到快取讀取。
* Chat 顯式 `cache_control` 在上架前測試中連續命中 1,657 tokens；APIYI Default 分組線上複測第二輪同樣命中 1,657 tokens。隱式快取命中不夠穩定。
* 快取讀掛牌價為 \$0.075 / 1M tokens。

> [!WARNING]
>
> **usage 中的快取欄位不等於實際賬單。** 是否命中、快取 token 數與最終優惠請以控制台單條日誌的計費詳情為準，不要只憑介面回顯判斷。

## 引數相容性

| 引數 | 實測行為 |
| - | - |
| `temperature` | `1.5` 可用；`2.0` 返回範圍錯誤，支援區間為 `[0.0, 2.0)` |
| `top_p` | 支援，範圍 `(0.0, 1.0]` |
| `top_k` / `presence_penalty` / `frequency_penalty` | 支援 |
| `stop` | 截斷生效 |
| `logprobs` / `top_logprobs` | 支援 |
| `partial: true` | 字首續寫可用 |
| `prefix: true` | 未得到正常續寫，請使用 `partial` |
| `n > 1` | 需要關閉思考 |
| `seed` | 同 seed 兩次輸出不同，不保證確定性復現 |
| 未知引數 | 可能被靜默忽略，客戶端不應依賴此行為 |

`max_tokens=131072` 和 `200000` 曾被渠道接受並返回短答案，但這隻證明引數未被拒絕，不代表已驗證對應長度的實際生成能力。

## 常見問題

> [accordion] 為什麼 HTTP 200 但沒有正文？
>
> 預設思考可能耗盡較小的 `max_tokens`，響應終止原因為 `length`。請關閉思考或提高輸出預算，並檢查 `reasoning_content` 與 `finish_reason`。

> [accordion] Responses 或 Claude Code 能直接用嗎？
>
> 可以。Responses 客戶端推薦 CodexResponses 分組，Claude Code 推薦 ClaudeCode 分組；Default 分組令牌的三端點最小請求也已通過。Responses 的 `tool_choice="required"` 在原廠測試中被忽略，強制結構化場景建議使用具名工具或 Chat；Messages 不支援 OpenAI 風格的 `response_format`，且 `max_tokens` 必填，結構化輸出請改用工具呼叫。Claude Code 的複雜 Agent 工作流建議按客戶端版本先灰度驗證。

> [accordion] 如何降低日常呼叫成本？
>
> 日常對話和結構化抽取顯式設定 `reasoning_effort="none"`，長文複用固定字首並核對控制台快取計費詳情；符合檔位時疊加充值加贈。

> [accordion] 可以直接宣傳最大輸出為 200K 嗎？
>
> 不建議。渠道接受 `max_tokens=200000` 不等於完成過 200K 實際生成。本頁不據此標註最大輸出長度。

## 相關文件

* [模型價格](https://docs.apiyi.com/zh-Hant/models/index.md) — 最新價格、分組與端點
* [充值優惠活動](https://docs.apiyi.com/zh-Hant/faq/recharge-promotions.md) — 階梯加贈規則與等效折扣
* [Qwen3.8-Max 概覽](https://docs.apiyi.com/zh-Hant/api-capabilities/qwen-3-8/overview.md) — 上一代模型
* [API 使用手冊](https://docs.apiyi.com/zh-Hant/api-manual.md) — 通用鑑權、呼叫與錯誤處理

> [!NOTE]
>
> 本頁實測依據為 2026-11-17 (UTC+8) 的 325 次上架前呼叫，以及同日在 APIYI Default 分組完成的 15 次線上驗收；線上驗收覆蓋 Chat、Responses、Messages、流式、工具、JSON Schema、圖片、影片、快取和 32K 上下文。官方資料：`https://qwen.ai/blog?id=qwen4-max`。模型與渠道行為可能調整，以實際呼叫和控制台計費詳情為準。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.