> ## 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/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/models/index.md)栏目为准。充值活动采用余额加赠，等效折扣约 83–91 折，详见[充值优惠活动](https://docs.apiyi.com/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/models/index.md) — 最新价格、分组与端点
* [充值优惠活动](https://docs.apiyi.com/faq/recharge-promotions.md) — 阶梯加赠规则与等效折扣
* [Qwen3.8-Max 概览](https://docs.apiyi.com/api-capabilities/qwen-3-8/overview.md) — 上一代模型
* [API 使用手册](https://docs.apiyi.com/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.