> ## 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.

# DeepSeek V4 Flash Responses API 参考

> DeepSeek V4 Flash 正式版（deepseek-v4-flash-ga-260731）Responses API 参考与在线调试：支持显式缓存链式调用，实测每轮整体命中上一轮全部上下文。

<Info>
  右侧 Playground 可直接调试：在 **Authorization** 填 `Bearer sk-your-api-key`。
  默认示例已带 `caching: {"type": "enabled"}` 与 `store: true`，是显式缓存链式调用的首轮写入形态。
</Info>

<Tip>
  Responses 端相比 Chat Completions 多一层**显式缓存**。模型能力、定价、思考控制详见
  [DeepSeek V4 Flash 概览](/api-capabilities/deepseek-v4-flash/overview)。
</Tip>

<Warning>
  * **`text.format` 的 json\_schema 不生效**：返回 200 但完全无视 schema，3/3 次被代码围栏包裹导致解析失败
  * **`web_search` 后端不可用**：工具已接通（能看到 `web_search_call`、`status: completed`），但 6/6 次搜索报错、不返回 `results`
  * **`mcp` 返回 `AccessDenied`**：账号 / 渠道级内置工具权限问题，换合法 server 地址结果相同
  * 纯文本模型，传图片会报 `Model do not support image input`
</Warning>

## 参数说明速查

| 参数                     | 类型             | 必填 | 默认      | 说明                                         |
| ---------------------- | -------------- | -- | ------- | ------------------------------------------ |
| `model`                | string         | ✓  | —       | 固定 `deepseek-v4-flash-ga-260731`           |
| `input`                | string / array | ✓  | —       | 字符串或标准 Responses 消息数组，纯文本                  |
| `max_output_tokens`    | int            |    | —       | 硬上限 393,216，思考内容计入                         |
| `store`                | bool           |    | `true`  | 链式调用必须为 `true`                             |
| `previous_response_id` | string         |    | —       | 上一轮响应 `id`，配合 `caching` 命中显式缓存             |
| `caching.type`         | string         |    | —       | `enabled` 写入显式缓存；响应会回显该字段                  |
| `reasoning.effort`     | string         |    | —       | `minimal` 实测思考 tokens 恒为 0；其余档位非单调         |
| `stream`               | bool           |    | `false` | SSE 流式，实测 TTFB 约 2.31 秒                    |
| `tools`                | array          |    | —       | `function` 类型可用；`web_search` / `mcp` 见上方警告 |

## 显式缓存：必须走链式调用

<Warning>
  **常见误用**：把同一段长前缀重复发两次并带上 `caching`，`cached_tokens` 会一直是 0。
  显式缓存**不是**按前缀匹配的，必须用 `previous_response_id` 把会话链起来。
</Warning>

正确姿势：首轮传完整长文写入缓存，后续轮只传新问题并链上一轮的 `id`。

| 轮次    | 调用方式                               | input\_tokens | cached\_tokens | 耗时    |
| ----- | ---------------------------------- | ------------- | -------------- | ----- |
| 1（写入） | `caching: enabled` + `store: true` | 15,629        | 0              | 4.10s |
| 2     | + `previous_response_id`           | 15,664        | **15,629**     | 5.18s |
| 3     | + `previous_response_id`           | 15,701        | **15,664**     | 4.57s |
| 4     | + `previous_response_id`           | 15,738        | **15,701**     | 4.54s |

每一轮把上一轮的全部上下文整体命中。做长文档连续追问时，这个模式比每轮重发全文省得多。

### 链式调用示例

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

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1",
)

long_doc = open("report.md").read()

# 第 1 轮：写入缓存
first = client.responses.create(
    model="deepseek-v4-flash-ga-260731",
    input=long_doc + "\n\n请总结这份报告的核心结论。",
    max_output_tokens=800,
    store=True,
    extra_body={"caching": {"type": "enabled"}},
)
print(first.output_text)

# 第 2 轮起：只传新问题，链上一轮 id
second = client.responses.create(
    model="deepseek-v4-flash-ga-260731",
    input="其中第三节提到的风险有哪些？",
    previous_response_id=first.id,
    max_output_tokens=800,
    store=True,
    extra_body={"caching": {"type": "enabled"}},
)
print(second.output_text)
print("缓存命中：", second.usage.input_tokens_details.cached_tokens)
```

## 隐式缓存

不传 `caching` 时隐式缓存同样生效，相同长前缀重复请求命中 99.9%（15,633 → 15,616）。
两种缓存可按场景选择：**同一份前缀被很多独立请求复用**走隐式缓存，
**同一个会话连续多轮追问**走显式缓存链式调用。

## 输出项类型

响应的 `output` 是数组，可能包含以下 item：

| type              | 说明                                       |
| ----------------- | ---------------------------------------- |
| `reasoning`       | 思考内容（`reasoning.effort` 非 `minimal` 时出现） |
| `message`         | 最终回答，文本在 `content[].text`                |
| `function_call`   | 工具调用，带 `call_id` 与 `arguments`           |
| `web_search_call` | 搜索调用记录，**当前不含 `results` 字段**             |


## OpenAPI

````yaml api-reference/deepseek-v4-flash-responses-openapi.yaml POST /v1/responses
openapi: 3.1.0
info:
  title: DeepSeek V4 Flash Responses API
  description: >
    DeepSeek V4 Flash 正式版（`deepseek-v4-flash-ga-260731`）—— OpenAI 兼容 Responses
    端点。


    相比 Chat Completions，Responses 端多一层**显式缓存**：


    - 首轮带 `caching: {"type": "enabled"}` 写入缓存

    - 后续轮用 `previous_response_id` 链式调用，实测每轮整体命中上一轮全部上下文

    - 注意：把同一段长前缀重复发两次**不会**命中显式缓存，必须走链式


    已知不可用项：`text.format` 的 json_schema 收参但不约束 schema；

    `web_search` 工具已接通但搜索后端持续报错；`mcp` 工具返回 `AccessDenied`。


    **认证方式**：在请求头中添加 `Authorization: Bearer YOUR_API_KEY`


    **获取 API Key**：访问 API易控制台 `api.apiyi.com/token` 创建令牌
  version: 1.0.0
servers:
  - url: https://api.apiyi.com
    description: 主要端点
  - url: https://vip.apiyi.com
    description: 备用端点
security:
  - bearerAuth: []
paths:
  /v1/responses:
    post:
      tags:
        - 文本生成
      summary: Responses：DeepSeek V4 Flash 文本生成（支持显式缓存链式调用）
      description: |
        使用 `deepseek-v4-flash-ga-260731` 调用 Responses 端点。

        典型的多轮长上下文用法：

        1. 首轮传完整长文 + `caching: {"type": "enabled"}` + `store: true`
        2. 记下响应里的 `id`
        3. 后续轮只传新问题 + `previous_response_id`，上一轮上下文整体命中缓存
      operationId: createDeepSeekV4FlashResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeepSeekV4FlashResponsesRequest'
            example:
              model: deepseek-v4-flash-ga-260731
              input: 用一句话说明什么是 MoE 架构。
              max_output_tokens: 500
              store: true
              caching:
                type: enabled
      responses:
        '200':
          description: 生成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeepSeekV4FlashResponsesResponse'
        '400':
          description: >-
            参数非法。常见：输入超过 1,048,570 tokens、传入图片内容（返回 Model do not support image
            input）
        '401':
          description: 未授权 - API Key 无效
        '403':
          description: 无内置工具权限（使用 mcp 等内置工具时返回 AccessDenied）
        '429':
          description: 请求频率超限或余额不足
      security:
        - bearerAuth: []
components:
  schemas:
    DeepSeekV4FlashResponsesRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: 模型 ID，固定 deepseek-v4-flash-ga-260731
          enum:
            - deepseek-v4-flash-ga-260731
          default: deepseek-v4-flash-ga-260731
        input:
          description: 输入内容。可为字符串，或 OpenAI Responses 标准的消息数组。纯文本，不支持图片
          oneOf:
            - type: string
            - type: array
              items:
                type: object
        max_output_tokens:
          type: integer
          description: 最大输出 tokens，硬上限 393,216。思考内容也计入
          default: 500
          maximum: 393216
        store:
          type: boolean
          description: 是否存储本轮响应。使用 previous_response_id 链式调用时需要为 true
          default: true
        previous_response_id:
          type: string
          description: 上一轮响应的 id。配合 caching 使用可整轮命中显式缓存
        caching:
          type: object
          description: '显式缓存开关。首轮传 {"type": "enabled"} 写入，后续轮配合 previous_response_id 命中'
          properties:
            type:
              type: string
              enum:
                - enabled
                - disabled
              default: enabled
        reasoning:
          type: object
          description: 思考控制。实测 effort=minimal 时 reasoning_tokens 恒为 0；其余档位不构成单调阶梯
          properties:
            effort:
              type: string
              enum:
                - minimal
                - low
                - medium
                - high
                - max
        stream:
          type: boolean
          description: 是否流式输出（SSE）。实测 TTFB 约 2.3 秒
          default: false
        tools:
          type: array
          description: 工具列表。function 类型实测可用；web_search 已接通但后端报错，mcp 返回 AccessDenied
          items:
            type: object
    DeepSeekV4FlashResponsesResponse:
      type: object
      properties:
        id:
          type: string
          description: 响应 ID，用作下一轮的 previous_response_id
        model:
          type: string
        output:
          type: array
          description: 输出项数组。可能包含 reasoning / message / function_call / web_search_call 等类型
          items:
            type: object
        caching:
          type: object
          description: 显式缓存状态回显
        usage:
          type: object
          description: >-
            用量。input_tokens_details.cached_tokens
            为缓存命中量；output_tokens_details.reasoning_tokens 为思考消耗
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 在 API易控制台获取的 API Key

````