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

# GPT-5.6（Prompt Caching）

> GPT-5.6 系列对话接口与 Prompt Caching 显式/隐式缓存机制

<Note>
  通用多模型 Chat Completions 说明见 [原生 OpenAI 格式（ChatCompletions）](/cn/api-reference/endpoint/chat-openai)，Responses API 用法见 [原生 OpenAI 格式（Responses）](/cn/api-reference/endpoint/responses-openai)。本文聚焦 GPT-5.6 系列模型及其 Prompt Caching 缓存机制。
</Note>

## 简介

GPT-5.6 是 OpenAI 于 2026 年 7 月 GA 的最新旗舰模型系列，上下文长度 **1M**。它是首个把「隐式缓存」与「显式缓存」统一成一套机制的模型，也是第一个「缓存写入收费」的系列：**缓存读取按输入价的 10% 计费，缓存写入按输入价的 1.25 倍计费**。

合理使用缓存可以显著降低长前缀场景（系统提示词、RAG、知识库、多轮对话）的调用成本——这也是 GPT-5.6 官方推荐的降本手段。

## 模型系列

| 模型              | 定位 | 上下文长度 | 特点                             | 推荐场景             |
| --------------- | -- | ----- | ------------------------------ | ---------------- |
| `gpt-5.6-sol`   | 旗舰 | 1M    | 系列最强，前沿推理与长程 Agent，支持 max 深度推理 | 复杂编码、长程 Agent、科研 |
| `gpt-5.6-terra` | 均衡 | 1M    | 性能对标 GPT-5.5，成本约为 Sol 的一半      | 日常开发、高频生产        |
| `gpt-5.6-luna`  | 轻量 | 1M    | 速度最快、成本最低                      | 高并发、意图分类、批量处理    |

## 认证

<ParamField header="Authorization" type="string" required>
  Bearer Token，如 `Bearer sk-xxxxxxxxxx`
</ParamField>

## 请求参数

<ParamField body="model" type="string" required>
  模型标识，支持：

  * `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`
</ParamField>

<ParamField body="messages" type="array" required>
  对话消息列表，每个元素包含 `role`（user/system/assistant）和 `content`。`content` 支持 OpenAI v2 多模态数组，显式缓存断点就打在 `content` 数组的某个元素上
</ParamField>

<ParamField body="prompt_cache_key" type="string">
  GPT-5.6 系列专属参数。用于精确匹配可复用的缓存前缀，建议按「租户:场景:版本」组织（如 `tenant:acme:support-v1`）。不传时缓存匹配精度会下降，命中率不可控
</ParamField>

<ParamField body="prompt_cache_options" type="object">
  缓存模式配置（GPT-5.6 系列专属）：

  * `mode`：`"implicit"`（默认，隐式缓存）或 `"explicit"`（显式缓存，禁用自动断点）
  * `ttl`：固定 `"30m"`，表示缓存「至少存活 30 分钟」（可带可不带）
</ParamField>

**`prompt_cache_breakpoint`**（object，非顶层请求体字段）

显式缓存断点，**嵌套在 `messages` 里某条消息的 `content` 数组的块上**（`text` / `image_url` / `input_audio` / `file` / `refusal`），取值 `{"mode": "explicit"}`，表示「该块之前的内容都要缓存」。`mode` 只接受 `"explicit"`，其它取值或打在不可缓存的块上会返回 `400 invalid_request_error`

<ParamField body="reasoning_effort" type="string" default="medium">
  推理强度（GPT-5.6 系列专属，替代传统采样参数），取值：`none` / `low` / `medium`（默认）/ `high` / `xhigh` / `max`。`none` 关闭思考；`max` 为 `gpt-5.6-sol` 深度推理档位
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  是否启用流式输出，返回 SSE 格式的分片数据
</ParamField>

<ParamField body="max_tokens" type="number">
  最大生成 token 数，控制回复长度
</ParamField>

<ParamField body="verbosity" type="string" default="medium">
  输出详细程度（GPT-5.6 系列专属），取值：`low` / `medium` / `high`。控制回答长短；注意不要用提高 verbosity 代替推理
</ParamField>

## 基础示例

<Tabs>
  <Tab title="普通对话">
    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.6-luna",
        "messages": [
          {"role": "system", "content": "你是一个有用的助手"},
          {"role": "user", "content": "请用中文简要介绍人工智能"}
        ],
        "reasoning_effort": "low",
        "verbosity": "medium"
      }'
    ```
  </Tab>

  <Tab title="显式缓存：首次创建（cache miss）">
    打上 `prompt_cache_breakpoint` 的第一次调用会同时完成「创建缓存」：断点之前的内容被写入缓存。本次响应 `cache_write_tokens > 0`、`cached_tokens = 0`，前缀部分按写入价（输入价的 1.25 倍）计费：

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.6-luna",
        "prompt_cache_key": "tenant:acme:support-assistant-v1",
        "prompt_cache_options": {"mode": "explicit"},
        "messages": [
          {
            "role": "system",
            "content": [
              {
                "type": "text",
                "text": "You are a support assistant. <这里放 1024+ tokens 的稳定系统提示词/知识库内容>",
                "prompt_cache_breakpoint": {"mode": "explicit"}
              }
            ]
          },
          {"role": "user", "content": "第一个用户的问题"}
        ],
        "max_tokens": 128
      }'
    ```
  </Tab>

  <Tab title="显式缓存：命中（cache hit）">
    第二次及之后调用：`prompt_cache_key` 不变、断点之前的内容逐字节一致、TTL 30 分钟内，直接复用缓存。本次响应 `cached_tokens > 0`、`cache_write_tokens = 0`，缓存部分按读取价（输入价的 10%）计费：

    ```bash theme={null}
    curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -d '{
        "model": "gpt-5.6-luna",
        "prompt_cache_key": "tenant:acme:support-assistant-v1",
        "prompt_cache_options": {"mode": "explicit"},
        "messages": [
          {
            "role": "system",
            "content": [
              {
                "type": "text",
                "text": "You are a support assistant. <与首次创建完全一致的内容>",
                "prompt_cache_breakpoint": {"mode": "explicit"}
              }
            ]
          },
          {"role": "user", "content": "换了新问题，但前缀不变"}
        ],
        "max_tokens": 128
      }'
    ```

    <Note>
      * 断点之前的 1200 tokens 逐字节一致、仅断点之后的 user 消息不同 → 第二次调用命中缓存
      * 前缀任意字节变化（哪怕 1 个字符）都会导致 cache miss，重新写入
    </Note>
  </Tab>

  <Tab title="Python 示例">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.gravitex.ai/v1"
    )

    # 普通对话
    completion = client.chat.completions.create(
        model="gpt-5.6-luna",
        messages=[
            {"role": "system", "content": "你是一个有用的助手"},
            {"role": "user", "content": "请用中文简要介绍人工智能"}
        ]
    )
    print(completion.choices[0].message.content)

    # 显式缓存：缓存字段通过 extra_body 传入
    completion = client.chat.completions.create(
        model="gpt-5.6-luna",
        messages=[
            {
                "role": "system",
                "content": [
                    {
                        "type": "text",
                        "text": "You are a support assistant. <1024+ tokens 稳定内容>",
                        "prompt_cache_breakpoint": {"mode": "explicit"},
                    }
                ],
            },
            {"role": "user", "content": "第一个用户的问题"},
        ],
        extra_body={
            "prompt_cache_key": "tenant:acme:support-assistant-v1",
            "prompt_cache_options": {"mode": "explicit"},
        },
    )
    usage = completion.usage
    print(usage.prompt_tokens_details.cached_tokens)        # 命中缓存的 token 数
    print(usage.prompt_tokens_details.cache_write_tokens)   # 新写入缓存的 token 数
    ```
  </Tab>
</Tabs>

## 高级功能

### Prompt Caching（缓存机制）

#### 隐式缓存 vs 显式缓存

| 模式     | 触发方式                                                    | 特点                                                                    | 适用场景                       |
| ------ | ------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------- |
| 隐式（默认） | 无需任何字段，OpenAI 自动对对话前缀做最长公共前缀匹配（对应「读取回溯断点数」中最近 50 个历史断点） | 零配置，但依赖自动匹配，长 RAG / 多段文档场景容易匹配不到最优前缀                                  | 请求内容相对固定的普通对话              |
| 显式     | 在内容块上手动加 `prompt_cache_breakpoint: {"mode":"explicit"}` | 精确控制哪段前缀被缓存，命中率可控；配合 `prompt_cache_options.mode:"explicit"` 可完全禁用自动断点 | 稳定系统提示词 / 知识库 / 文件输入等长前缀场景 |

两种模式计费相同，只是命中率的可控程度不同。平台会原样透传这些字段给上游（OpenAI 官方原生 API）。

#### 没有独立的「创建缓存」接口

OpenAI 不像 Gemini 那样提供单独的缓存创建接口（`cachedContents.create`）。**「创建缓存」和「正常对话请求」是同一个 API 调用**：打 `prompt_cache_breakpoint` 只是告诉 OpenAI「断点之前的内容值得缓存」，写入动作是本次请求的副作用——

1. 正常调用 `/v1/chat/completions`，在某个内容块上加 `prompt_cache_breakpoint`；
2. 服务端检查断点之前的内容是否命中：
   * **未命中**（首次 / 已过期）→ 正常推理 + 把断点前内容写入缓存 → `cache_write_tokens > 0`、`cached_tokens = 0`；
   * **命中**（`prompt_cache_key` 一致、前缀逐字节一致、TTL 内）→ 直接复用 → `cached_tokens > 0`、`cache_write_tokens = 0`；
3. 写入成功后 30 分钟 TTL 内，后续调用只「读」不「重写」；超过 30 分钟无访问，下一次调用退回「cache miss → 重新写入」。

#### 限制

| 限制       | 说明                                                                         |
| -------- | -------------------------------------------------------------------------- |
| 最小可缓存前缀  | 1024 tokens（与老模型一致）                                                        |
| 每请求最大新写入 | **4 个**（隐式模式的自动断点占 1 个写入槽，显式断点最多再写 3 个；纯显式模式最多写 4 个）                       |
| 读取回溯断点数  | 最多匹配对话里最近 **50 个断点**，命中其中最长前缀                                              |
| 缓存存续时间   | `prompt_cache_options.ttl` 固定 `"30m"`（不保证更长）                               |
| 非法断点     | `mode` 非 `"explicit"`、或打在不可缓存的块上 → `400 invalid_request_error`             |
| 老模型兼容    | GPT-5.6 之前的模型收到 `prompt_cache_options` / `prompt_cache_breakpoint` 会直接报错拒绝 |

#### 计费

| 项            | 单价（对比输入价） | 说明                            |
| ------------ | --------- | ----------------------------- |
| 缓存读取（cached） | **10%**   | 命中缓存的输入 token 按此价计费，90% off   |
| 缓存写入（write）  | **125%**  | 新写入缓存的输入 token 按输入价的 1.25 倍计费 |
| 未缓存输入        | 100%      | 断点之外、未命中缓存的部分按正常输入价计费         |

> 以 `gpt-5.6-luna`（输入 $1.00/1M tokens）为例：写入缓存 $1.25/1M、读取缓存 \$0.10/1M。前缀越稳定、请求次数越多，节省越明显。

### 工具调用（Functions / Tools）

GPT-5.6 支持标准 OpenAI 工具调用格式，用法与 [原生 OpenAI 格式（ChatCompletions）](/cn/api-reference/endpoint/chat-openai) 中的工具调用章节一致：

```bash theme={null}
curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [
      {"role": "user", "content": "上海的天气怎么样？"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "根据城市获取天气信息",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string"}
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'
```

### 结构化输出（JSON Schema）

GPT-5.6 支持通过 `response_format` 参数控制输出格式：

```bash theme={null}
curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gpt-5.6-luna",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "Answer",
        "schema": {
          "type": "object",
          "properties": {
            "summary": {"type": "string"}
          },
          "required": ["summary"]
        }
      }
    },
    "messages": [
      {"role": "user", "content": "返回一个包含 summary 字段的 JSON"}
    ]
  }'
```

<Tip>
  严格的结构化输出建议使用较低推理强度（如 `reasoning_effort: "low"` 或 `"none"`），并设置合适的 `max_tokens` 以提升一致性。
</Tip>

### 思考能力（Reasoning）

GPT-5.6 三款均为推理模型，思考深度由 `reasoning_effort` 控制（取值见 [请求参数](#请求参数)）：

| 取值               | 说明                        |
| ---------------- | ------------------------- |
| `none`           | 关闭思考，直接生成                 |
| `low`            | 轻量思考，适合简单问答               |
| `medium`（默认）     | 标准思考                      |
| `high` / `xhigh` | 深度思考，适合复杂任务               |
| `max`            | 仅 `gpt-5.6-sol` 支持的深度推理档位 |

<Note>
  推理模型不开放传统采样参数：`temperature` / `top_p` 自定义值不生效（会被忽略或回退默认值）。控制输出请用 `reasoning_effort`（思考深度）与 `verbosity`（回答详细程度）；`gpt-5.6-sol` 使用函数工具时，请留意官方对推理强度取值的限制。
</Note>

思考过程消耗的 token 会体现在 `usage.completion_tokens_details.reasoning_tokens` 中，详见下方 [usage 字段说明](#usage-字段说明)。

## usage 字段说明

调用 `/v1/chat/completions` 时，响应中的 `usage` 对象包含 token 用量统计。GPT-5.6 的核心是 `prompt_tokens_details` 下新增的缓存字段：

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1752345600,
  "model": "gpt-5.6-luna",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这是模型的回复内容"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1300,
    "completion_tokens": 85,
    "total_tokens": 1385,

    "prompt_tokens_details": {
      "cached_tokens": 1200,
      "cache_write_tokens": 0,
      "text_tokens": 1300,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 85,
      "audio_tokens": 0,
      "image_tokens": 0,
      "reasoning_tokens": 0
    },

    "input_tokens": 1300,
    "output_tokens": 85,
    "input_tokens_details": null
  }
}
```

| 字段                                                                    | 什么时候会有值                   | 说明                                                                           |
| --------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------- |
| `prompt_tokens`                                                       | 始终                        | 输入 token 总数（含缓存部分）                                                           |
| `completion_tokens`                                                   | 始终                        | 输出 token 总数                                                                  |
| `total_tokens`                                                        | 始终                        | `prompt_tokens + completion_tokens`                                          |
| `prompt_tokens_details.cached_tokens`                                 | 命中缓存时                     | 命中缓存、按缓存读取价（输入价的 10%）计费的输入 token 数                                           |
| `prompt_tokens_details.cache_write_tokens`                            | 仅 GPT-5.6 及以上、本次产生新缓存写入时  | 新写入缓存、按缓存写入价（输入价的 1.25 倍）计费的输入 token 数。**OpenAI 官方原生 API 专属字段**，Azure 渠道不会返回 |
| `prompt_tokens_details.text_tokens` / `audio_tokens` / `image_tokens` | 始终存在                      | 输入中文本 / 音频 / 图片部分的 token 拆分，纯文本场景下音频、图片为 `0`                                 |
| `completion_tokens_details.reasoning_tokens`                          | 仅推理模型（GPT-5.6 Sol 等）启用思考时 | 模型内部思考消耗的 token 数，不进入最终回复文本，但按输出价计费                                          |
| `input_tokens` / `output_tokens`                                      | 始终                        | 数值上等同于 `prompt_tokens` / `completion_tokens`，为兼容部分上游协议保留的别名                  |
| `input_tokens_details`                                                | 目前对话场景下基本为 `null`         | 保留字段，普通对话请求不会填充                                                              |

<Note>
  * `cached_tokens` 与 `cache_write_tokens` **不会同时非零**：一段内容不可能同时是「新写入」又「命中」。
  * 若始终看不到 `cache_write_tokens` 非零，请确认：① 请求带上了 `prompt_cache_options` / `prompt_cache_breakpoint`；② 前缀超过 1024 tokens；③ 请求没有走 Azure 渠道（`cache_write_tokens` 为 OpenAI 官方原生 API 专属字段，Azure 渠道不返回，见上方字段说明表）。
</Note>

## 响应格式

<Tabs>
  <Tab title="非流式响应">
    ```json theme={null}
    {
      "id": "chatcmpl-xxx",
      "object": "chat.completion",
      "created": 1234567890,
      "model": "gpt-5.6-luna",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "回复内容..."
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 1300,
        "completion_tokens": 85,
        "total_tokens": 1385,
        "prompt_tokens_details": {
          "cached_tokens": 1200,
          "cache_write_tokens": 0
        }
      }
    }
    ```

    `usage` 各字段的完整说明见上方 [usage 字段说明](#usage-字段说明)。
  </Tab>

  <Tab title="流式响应">
    流式响应以 SSE（Server-Sent Events）格式返回，每个分片包含部分内容，最后一个分片通常包含 `usage` 统计信息（含缓存字段）：

    ```json theme={null}
    data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"gpt-5.6-luna","choices":[{"index":0,"delta":{"content":"回"},"finish_reason":null}]}

    data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"gpt-5.6-luna","choices":[{"index":0,"delta":{"content":"复"},"finish_reason":null}]}

    data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"gpt-5.6-luna","choices":[],"usage":{"prompt_tokens":1300,"completion_tokens":85,"prompt_tokens_details":{"cached_tokens":1200,"cache_write_tokens":0}},"finish_reason":"stop"}

    data: [DONE]
    ```
  </Tab>
</Tabs>

## 错误处理

| 异常类型                     | 触发场景                                                               | 返回信息                                 |
| ------------------------ | ------------------------------------------------------------------ | ------------------------------------ |
| AuthenticationError      | API 密钥无效或未授权                                                       | 错误：API密钥无效或未授权                       |
| NotFoundError            | 模型不存在或不被支持                                                         | 错误：模型 \[model] 不存在或不被支持              |
| APIConnectionError       | 网络中断或服务器未响应                                                        | 错误：无法连接到API服务器                       |
| APIError                 | 请求格式错误等服务端异常                                                       | API请求失败：\[错误详情]                      |
| InvalidRequestError（400） | 显式缓存参数非法：`prompt_cache_breakpoint.mode` 非 `"explicit"`、断点打在不可缓存的块上 | invalid\_request\_error：缓存断点位置/取值不合法 |
| InvalidRequestError（400） | GPT-5.6 之前的模型收到 `prompt_cache_options` / `prompt_cache_breakpoint` | invalid\_request\_error：模型不支持显式缓存参数  |

## 支持的模型系列

`gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna` 三款模型的定位与推荐场景见上方 [模型系列](#模型系列)。完整模型列表请查看 [模型信息页面](/cn/api-reference/models)。

## 注意事项

<Note>
  * 使用显式缓存时务必带上 `prompt_cache_key`，否则匹配精度下降、命中率不可控
  * 缓存前缀要求逐字节一致：前缀内任意字节变化（包括格式、空白、图片编码）都会导致 cache miss 重新写入
  * 长前缀（>1024 tokens）是缓存生效的前提；前缀太短不会产生任何缓存写入
</Note>

## 相关资源

<Columns cols={2}>
  <Card title="ChatCompletions 通用接口" icon="chat" href="/cn/api-reference/endpoint/chat-openai">
    查看通用多模型对话接口说明
  </Card>

  <Card title="模型列表" icon="list" href="/cn/api-reference/models">
    查看所有支持的模型信息
  </Card>
</Columns>