> ## 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.
# Qwen3.8-Max Text Generation
> Alibaba Qwen's flagship Qwen3.8-Max: 2.4T-parameter sparse MoE, 1M context, 131K output, native image and video input. Listed on APIYI at $1.65/$4.95 per 1M tokens — 17.5% below official. Includes the capability matrix and pitfalls from 586 live test calls.
Qwen3.8-Max (`qwen3.8-max`) is Alibaba Qwen's new flagship, released August 3, 2026. It is a sparse MoE model with 2.4 trillion total parameters, a **1M context window**, 131K max output, and native support for text, image, and video input. APIYI listed it the day it shipped and ran **586 live test calls** against it — the capability matrix, parameter behavior, and billing notes on this page all come from those tests rather than from restating official documentation.
**Qwen3.8-Max is live on APIYI**: model name `qwen3.8-max`. **Thinking is on by default** (at the `xhigh` tier, and thinking tokens are billed as output), so set `reasoning_effort="none"` explicitly for everyday chat — in testing this took output from roughly 158 tokens down to 5. For the previous generation, see [Qwen3.6 series (legacy)](/en/api-capabilities/qwen-3-6/overview).
## Why this model
\$1.65 input, \$4.95 output per 1M tokens versus Alibaba Cloud's \$2/\$6. [Top-up promotions](/en/faq/recharge-promotions) stack on top.
Across 8K / 32K / 128K bodies with markers buried mid-document and at the tail, both endpoints recalled **all 6/6 exactly**. A 128K call takes about 80 seconds.
Text, image, and video input all verified working — no switching between a "long-context model" and a "vision model."
FrontierSWE rose from the previous generation's 40.7 to **73.5**, DeepSWE from 21.6 to 56.6. The tool-calling chain is complete, with two-round round-trips verified.
## Endpoint support
| Endpoint | Status | Notes |
| ---------------------- | ------------------------------ | ------------------------------------------------------------------------------------------- |
| `/v1/chat/completions` | ✅ Fully working | **Recommended.** Tool calling, structured output, multimodal, and streaming all verified |
| `/v1/messages` | ⚠️ Usable for code integration | Strip `thinking` blocks before replaying history — see "Using the Anthropic endpoint" below |
| `/v1/responses` | ❌ Not supported yet | All 30 test calls failed; reported upstream |
## Pricing
Per 1M tokens, pre-discount list price:
| Item | APIYI | Alibaba Cloud | Difference |
| ----------------------- | ------------- | ------------- | ----------- |
| Input | **\$1.65** | \$2.00 | 17.5％ lower |
| Output (incl. thinking) | **\$4.95** | \$6.00 | 17.5％ lower |
| Cache read | **\$0.20625** | \$0.25 | 17.5％ lower |
| Cache write | **\$2.0625** | — | — |
[Top-up promotions](/en/faq/recharge-promotions) stack on top for a lower effective cost.
## Specifications
| Item | Value |
| ------------------- | ------------------------------------------------------------------------------ |
| Model name | `qwen3.8-max` |
| Architecture | Sparse MoE, 2.4 trillion total parameters |
| Context window | 1M tokens (991K input without thinking, 983K with) |
| Max output | 131,072 tokens (out-of-range requests return the explicit bound `[1, 131072]`) |
| Max thinking budget | 262K tokens |
| Thinking mode | On by default, tier `xhigh` |
| Input modalities | Text, image, video |
| Output rate | \~19–22 tokens/s (measured) |
| Time to first token | \~1.85 s streaming (measured P50) |
Official benchmarks: 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.
## Controlling thinking (the most important section)
Qwen3.8-Max **thinks by default**, at the `xhigh` tier. Thinking tokens are billed as output and frequently account for over 90％ of it.
### Seven values, four real tiers
The parameter accepts 7 values but maps to only **4 real tiers** in practice:
| Value passed | Effective tier | Measured thinking |
| ------------------------ | ---------------------------------- | ----------------- |
| `none` | Thinking off | 0 tokens |
| `minimal` / `low` | Low | \~100 tokens |
| `medium` | Medium | \~150 tokens |
| `high` / `xhigh` / `max` | Default tier (all three identical) | \~150–175 tokens |
Passing `max` does not think harder than `xhigh`. Any other value returns a 400 listing the legal set.
### How to turn thinking off
```python theme={null}
response = client.chat.completions.create(
model="qwen3.8-max",
messages=[{"role": "user", "content": "Hello"}],
reasoning_effort="none",
max_tokens=500,
)
```
`enable_thinking: false` in `extra_body` and `chat_template_kwargs: {"enable_thinking": false}` are equivalent and also work.
**`max_tokens` does not bound thinking tokens.** We set `max_tokens=1` and were still billed **1,054** output tokens, 1,045 of them thinking.
`max_tokens` only truncates the visible answer. **Use `reasoning_effort` to control cost — do not rely on `max_tokens`.**
### `thinking_budget` has no effect
Passing 128 / 512 / 4096 all behave identically to the `low` tier; the number itself is ignored. **Use `reasoning_effort` instead.**
## Code examples
### Python (OpenAI SDK compatible)
```python theme={null}
from openai import OpenAI
client = OpenAI(
api_key="sk-your-apiyi-key",
base_url="https://api.apiyi.com/v1"
)
# Everyday chat: thinking off, fast and cheap
resp = client.chat.completions.create(
model="qwen3.8-max",
messages=[{"role": "user", "content": "Explain load balancing in one sentence."}],
reasoning_effort="none",
max_tokens=500,
)
print(resp.choices[0].message.content)
# Hard reasoning: keep the default thinking tier
resp = client.chat.completions.create(
model="qwen3.8-max",
messages=[{"role": "user", "content": "Prove that among any 5 integers, some 3 sum to a multiple of 3."}],
max_tokens=4000,
)
print(resp.choices[0].message.reasoning_content) # thinking trace
print(resp.choices[0].message.content) # final answer
```
### Image input
```python theme={null}
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": "What number is written in this image?"},
{"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
]}],
max_tokens=500,
)
```
Remote image URLs also work on this endpoint — just set `url` to an `https://...` address.
### Video input
```python theme={null}
resp = client.chat.completions.create(
model="qwen3.8-max",
messages=[{"role": "user", "content": [
{"type": "text", "text": "What happens in this video?"},
{"type": "video_url", "video_url": {"url": f"data:video/mp4;base64,{b64_video}"}},
]}],
max_tokens=1000,
)
```
Video understanding took **144–285 seconds** per call in testing. Set your client timeout above 300 seconds and prefer streaming or an async task queue.
There is also a frame-sequence form, `{"type": "video", "video": [frame1, frame2, ...]}`, which requires **4–8000 frames** — fewer than 4 returns a 400.
### cURL
```bash theme={null}
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": "Hello"}],
"reasoning_effort": "none"
}'
```
## Tool calling
Tool calling on the Chat Completions endpoint is **fully working**: single tool, parallel tools, two-round round-trip, picking 1 out of 20 tools, streaming deltas, and `parallel_tool_calls: false` all verified.
**Forced tool calls require thinking off.** When `tool_choice` is `"required"` or names a specific function, you must also set `reasoning_effort="none"` — otherwise you get a 400 (`tool_choice does not support being set to required or object in thinking mode`) or the call is silently skipped.
`tool_choice` set to `"auto"` / `"none"` is unaffected. The same applies to `n > 1`.
```python theme={null}
resp = client.chat.completions.create(
model="qwen3.8-max",
messages=[{"role": "user", "content": "What's the weather in Beijing?"}],
tools=tools,
tool_choice={"type": "function", "function": {"name": "get_weather"}},
reasoning_effort="none", # required
)
```
## Structured output
`response_format` with `json_schema` held **strictly** in testing: nested objects, enums, arrays, and `additionalProperties: false` all took effect, with no extra fields and no Markdown fences.
**Disable thinking for structured output.** Same schema, measured side by side:
| Configuration | Output tokens | Of which thinking | Latency |
| ----------------------------------------- | ------------- | ----------------- | ------- |
| `json_schema` + default thinking | 4,066 | 3,971 | 100 s |
| `json_schema` + `reasoning_effort="none"` | 154 | 0 | 4.7 s |
Conformance was identical; cost and latency differ by an order of magnitude.
## Context caching
* **Hit threshold around 1,024 tokens**: an 818-token prefix missed; 1,070 tokens and up hit
* **Real multi-turn conversations do hit**: appending messages turn by turn hit on every round
* **Long documents benefit most**: 98.6％ cached input at 128K, 99.3％ at 32K
Cache hits were **not stable** in testing — the same prefix hit on some rounds and missed on others, and TTL cannot be reliably inferred from the API response. Treat caching as a bonus when it happens; **do not build cost projections on it.**
## Using the Anthropic endpoint
`/v1/messages` works for code integration, but you **must strip `thinking` blocks before replaying history**, otherwise you get a 400 (`if content is list. item must be dict and key[type] should in dict`).
```python theme={null}
def strip_thinking(blocks):
return [b for b in blocks if b.get("type") != "thinking"]
messages.append({"role": "assistant", "content": strip_thinking(resp["content"])})
```
With that filter in place, we verified 3-turn cross-turn memory, a two-round tool round-trip, and tool results persisting into later turns.
**Off-the-shelf clients such as Claude Code are not usable yet** — they replay history content blocks verbatim by default and their behavior cannot be changed, so the second turn returns 400. Use `/v1/chat/completions` instead.
Other differences on this endpoint: `response_format` is silently ignored (force a tool call for structured output), `tool_choice` only accepts the OpenAI format, images must be base64 (remote URLs return 400), and `reasoning_effort` has no effect (use `thinking: {"type": "disabled"}` to turn thinking off).
## Parameter compatibility
| Parameter | Status | Notes |
| -------------------------------------------------- | ------ | ------------------------------------------------------------------------------------ |
| `temperature` | ✅ | Valid range `[0.0, 2.0)`; passing 2 returns 400 |
| `top_p` | ✅ | Valid range `(0.0, 1.0]` |
| `top_k` / `presence_penalty` / `frequency_penalty` | ✅ | |
| `stop` / `stop_sequences` | ✅ | Works on both endpoints |
| `logprobs` / `top_logprobs` | ✅ | |
| `stream` + `stream_options` | ✅ | Streaming always returns usage; long streams terminate cleanly with no tail stalling |
| `partial: true` | ✅ | Prefix continuation; no thinking during continuation |
| `n > 1` | ⚠️ | Requires `reasoning_effort="none"` |
| `seed` | ❌ | Same seed produced different output — determinism is not guaranteed |
| `prefix: true` | ❌ | No effect; use `partial: true` |
| `thinking_budget` | ❌ | The numeric value is ignored |
| Built-in web search | ❌ | Both `enable_search` and `tools: [{"type": "web_search"}]` are silently dropped |
## Best practices
Set `reasoning_effort="none"` explicitly. Measured latency dropped from \~5 s to 2 s, and output tokens to roughly 1/30.
128K recall was exact in testing, and long-document cache hit rates are high. Put the large document early in the message list and the question at the tail.
Constrain with `json_schema` and disable thinking. Conformance is unaffected.
Use `/v1/chat/completions`. Remember to disable thinking when forcing a tool call.
## FAQ
`max_tokens` bounds only the visible answer, not the thinking portion. We measured 1,054 output tokens billed at `max_tokens=1`. Use `reasoning_effort="none"` to control cost.
Forced tool choice is not supported while thinking is on. Pass `reasoning_effort="none"` alongside it.
This endpoint is not wired up for the model yet — all 30 test calls failed, with the error code alternating between 404 and 400. It has been reported upstream, and we will announce it in [Live Updates](/en/live) once it is available. Use `/v1/chat/completions` instead.
Not yet. The `/v1/messages` endpoint rejects history messages containing `thinking` blocks, and Claude Code replays them verbatim. When calling from your own code, strip those blocks and the endpoint works fine.
The model is served over more than one upstream route, and one of them does not report `reasoning_tokens` or `cached_tokens` — measured at roughly one third of chat requests. This has been reported upstream for alignment. Keep it in mind if you need exact thinking-cost accounting.
Video understanding measured 144–285 seconds per call; this is the model's own processing time. Set your timeout above 300 seconds and consider an async queue.
## Related
* [Qwen3.8-Max playground](/en/api-capabilities/qwen-3-8/chat-completions) — send requests directly
* [Qwen3.6 series (legacy)](/en/api-capabilities/qwen-3-6/overview) — the previous five models
* [Qwen3.8-Max launch notes](/en/news/qwen-3-8-max-launch) — benchmarks and full write-up
* [Model pricing](/en/models) — per-model rates, cache pricing, and available endpoints
* [Top-up promotions](/en/faq/recharge-promotions) — stackable discounts
Measurements on this page come from 586 live calls on 2026-08-03 (12:50–14:35 UTC+8). Billing-related conclusions are based on the usage fields returned by the API and were not cross-checked line by line against invoices. Model and gateway behavior may change as channels are adjusted — treat live calls as the source of truth.