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

# qwen3.8-max 接入指南

>  - OpenAI 兼容：chat/completions 与 Responses
- 内置工具仅 Responses 可用；思考不可关闭
- 支持隐式/显式上下文缓存、chat 端点 PDF 理解
- 计费 = token 费 + 工具按次费 

兼容 OpenAI SDK：替换 `base_url` 与 `api_key` 即可。模型名固定 **`qwen3.8-max`**。

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

client = OpenAI(
    api_key="<你的 APIMart key>",
    base_url="https://api.apimart.ai/v1",
)

resp = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "用一句话介绍杭州"}],
    stream=False,  # 必须显式传入，见下方注意
)
print(resp.choices[0].message.content)
```

通用接口说明：

* [Chat Completions](/cn/api-reference/texts/general/chat-completions)
* [OpenAI Responses](/cn/api-reference/texts/openai/responses)
* [模型价格接口](/cn/api-reference/texts/qwen3.8-max/pricing)

## 三件最容易踩的事

### 1. `/v1/chat/completions` 不传 `stream` 默认是流式

```python theme={null}
# 不传 stream → 返回 SSE 流，按非流式解析会失败
client.chat.completions.create(model="qwen3.8-max", messages=[...])

# 非流式必须显式传 False
client.chat.completions.create(
    model="qwen3.8-max",
    messages=[...],
    stream=False,
)
```

这与 OpenAI 官方默认（不传为非流式）**相反**，迁移代码时最容易踩坑。

### 2. 内置工具只在 `/v1/responses` 上可用

`/v1/chat/completions` **不支持**内置工具（传了会被忽略，**不报错**）。要用联网搜索、代码解释器、文搜图、图搜图，必须走 [Responses API](/cn/api-reference/texts/openai/responses)。

### 3. 工具名写错不会报错，只是永远不触发

错误工具名会被静默接受。**定价页上的 `t2i_search` / `i2i_search` 不是可用工具名**：

| 你可能看到的名字          | 实际要用的                  |
| ----------------- | ---------------------- |
| `t2i_search`（定价页） | **`web_search_image`** |
| `i2i_search`（定价页） | **`image_search`**     |

## 内置工具（Responses）

在 `/v1/responses` 的 `tools` 中声明，格式：`{"type": "<工具名>"}`。

| 工具名                | 作用                    | 约束                                      |
| ------------------ | --------------------- | --------------------------------------- |
| `web_search`       | 联网搜索网页并引用             | —                                       |
| `web_extractor`    | 抓取指定 URL 正文           | **必须与 `web_search` 同时声明**，单独使用会 **400** |
| `code_interpreter` | 沙箱执行代码                | —                                       |
| `web_search_image` | **文搜图**（搜网上已有图片，非文生图） | —                                       |
| `image_search`     | **图搜图**               | `input` 中需带图片；较慢，建议流式                   |

### 联网搜索

```python theme={null}
resp = client.responses.create(
    model="qwen3.8-max",
    input="用一句话说明上海明天天气",
    tools=[{"type": "web_search"}],
    max_output_tokens=600,
)
```

### 网页抓取

```python theme={null}
resp = client.responses.create(
    model="qwen3.8-max",
    input="抓取 https://example.com 并总结首屏内容",
    tools=[
        {"type": "web_search"},
        {"type": "web_extractor"},  # 缺少 web_search 会 400
    ],
)
```

典型错误信息：

```text theme={null}
The web_extractor tool must be executed with web_search tool.
```

### 图搜图

```python theme={null}
resp = client.responses.create(
    model="qwen3.8-max",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_image", "image_url": "https://example.com/your.jpg"},
            {"type": "input_text", "text": "找这张图的相似图片"},
        ],
    }],
    tools=[{"type": "image_search"}],
    stream=True,  # 建议流式：该工具耗时明显更长
)
```

### 如何确认工具被调用

以 **`usage.x_tools` 为准**（计费依据）：

```json theme={null}
{
  "output": [
    { "type": "reasoning" },
    { "type": "web_search_call" },
    {
      "type": "message",
      "content": [{ "type": "output_text", "text": "..." }]
    }
  ],
  "usage": {
    "input_tokens": 2528,
    "output_tokens": 362,
    "output_tokens_details": { "reasoning_tokens": 280 },
    "x_tools": { "web_search": { "count": 1 } }
  }
}
```

**声明了但模型未调用的工具不计费**——不会出现在 `x_tools` 中。

## 思考（推理）

**思考不可关闭**，每次请求都会先推理再作答：

* 思考内容按**输出 token** 计费，见 `output_tokens_details.reasoning_tokens`
* Responses：`output` 中的 `reasoning` item；chat 流式：`delta.reasoning_content`
* 传 `enable_thinking: false`：流式下无效；非流式会被降级处理，**不建议使用**

同一问题开思考时的输出 token 通常远高于不思考模型。控制成本请用 `max_output_tokens`。

## 上下文缓存

长 prompt 重复调用可降低输入成本。

### 隐式缓存（自动）

相同前缀的请求从第二次起可自动命中，命中部分按缓存价计费（约为普通输入的 1/8）。命中量按块取整，**不保证全部命中**。

### 显式缓存

在内容上标记 `cache_control`：

```python theme={null}
client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": "<很长的固定上下文>",
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {"role": "user", "content": "针对上面回答问题"},
    ],
    stream=False,
)
```

| 项      | 说明               |
| ------ | ---------------- |
| 最小缓存内容 | **≥ 1024 token** |
| 有效期    | **5 分钟**         |
| 创建缓存   | 比普通输入略贵          |
| 命中显式缓存 | 通常比隐式命中更便宜       |

响应区分：

```json theme={null}
// 创建
"prompt_tokens_details": {
  "cache_creation_input_tokens": 1482,
  "cache_type": "ephemeral",
  "cached_tokens": 0
}

// 命中
"prompt_tokens_details": {
  "cache_creation_input_tokens": 0,
  "cache_type": "ephemeral",
  "cached_tokens": 1482
}
```

隐式命中通常只有 `cached_tokens`，不一定带 `cache_type: "ephemeral"`。

## PDF 理解

**仅** `/v1/chat/completions` 支持。Responses API 会**静默忽略** PDF，不报错。

```python theme={null}
client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "file",
                "file": {"file_url": "https://example.com/doc.pdf"},
            },
            # 或 base64：
            # {"type": "file", "file": {"file_data": "data:application/pdf;base64,...", "filename": "doc.pdf"}}
            {"type": "text", "text": "这个文档讲了什么？"},
        ],
    }],
    stream=False,
)
```

* PDF 按图片理解，**按图片 token 计入输入**（约 letter \~2082 token/页、A4 \~2147 token/页量级）；**不额外收解析费**
* `fileid://` 写法**无效**（其它模型机制），会被当成纯文本

## 计费口径

总费用 = **token 费** + **工具按次费**（独立）。

| 项    | 计费方式                                  |
| ---- | ------------------------------------- |
| 输入   | 按 token；缓存命中走缓存价                      |
| 输出   | 按 token；**思考计入输出**                    |
| 内置工具 | 按 `usage.x_tools` **实际调用次数**（常按每千次计价） |

单价请查价格接口（见 [价格接口](/cn/api-reference/texts/qwen3.8-max/pricing)）：

```http theme={null}
GET /api/pricing/model?model=qwen3.8-max
```

读 `data.pricing.effective_rates`（已含分组折扣）与 `data.pricing.extras.tools`。

## 能力上限

| 项       | 值                       |
| ------- | ----------------------- |
| 最大输入    | 983,616 token（约 1M）     |
| 最大输出    | 131,072 token           |
| 缓存读 / 写 | 支持 / 支持                 |
| 多模态输入   | 图片、视频等（如 `input_image`） |

## 常见问题

**Q：传了 `tools` 但模型没调用？**\
① 是否用 `/v1/responses`；② 工具名是否正确（非 `t2i_search` 等）；③ `usage.x_tools` 是否有记录——没有即未调用、不收费。

**Q：`web_extractor` 400？**\
必须与 `web_search` 同时声明。

**Q：非流式很慢？**\
带工具（尤其 `image_search`）耗时更长。超时敏感场景建议直接流式。

**Q：能关掉思考省钱吗？**\
不能。用 `max_output_tokens` 控上限，或换支持关闭思考的模型。

**Q：怎么查用量？**

```http theme={null}
GET /v1/dashboard/billing/usage
GET /v1/dashboard/billing/subscription
```