From 7772bb5ba7921aa7d24331247a327453bc1d7c16 Mon Sep 17 00:00:00 2001
From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com>
Date: Wed, 26 Aug 2026 20:06:09 +0000
Subject: [PATCH] docs: include_usage streaming contract changed: no separate
usage-only chunk; usage rides on the final content chunk
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
The streaming semantics of the `include_usage` parameter were rewritten on both the Chat Completions and FIM Completion APIs (and mirrored in zh-cn). The docs previously promised that setting `include_usage` streams a dedicated usage-only chunk before `data: [DONE]` with an empty `choices` array; they now state that **no such separate chunk is emitted** — token usage statistics ride on the last content chunk, whose `choices` array contains exactly one element with no new content and a non-null `finish_reason`. This is a change to the shape of the stream that any code parsing per-chunk usage (e.g. looking for a `choices: []` chunk, or expecting `usage` on every chunk) can depend on, so it deserves human review.
Highlights, most interesting first:
- **No more usage-only chunk**: code that waits for an empty-`choices` chunk carrying `usage` may never see it now; usage arrives attached to the final content chunk instead.
- **`include_usage: false`/omitted behavior specified**: the `usage` field is now *absent* from all chunks except the last (previously docs implied it was present but `null` throughout). `true` still emits `usage` on every chunk, null on all but the last.
- **Both endpoints affected**: Chat Completions and FIM Completion (Beta) changed in lockstep, en + zh-cn, so no per-endpoint divergence.
- **Index churn only**: `.metadata.json` now resolves two previously-failed news pages (`news1226` → "🚀 Introducing DeepSeek-V3", `news250325` → "DeepSeek-V3-0324 Release"), but no news content pages were added — purely metadata, no review needed.
---
content/.metadata.json | 4 ++--
content/en/api/create-chat-completion.md | 6 ++++--
content/en/api/create-completion.md | 6 ++++--
content/zh-cn/api/create-chat-completion.md | 6 ++++--
content/zh-cn/api/create-completion.md | 6 ++++--
llms-full.txt | 12 ++++++++----
6 files changed, 26 insertions(+), 14 deletions(-)
diff --git a/content/.metadata.json b/content/.metadata.json
index da2c051..1a0ebbc 100644
--- a/content/.metadata.json
+++ b/content/.metadata.json
@@ -107,11 +107,11 @@
},
"content/en/news/news1226.md": {
"url": "https://api-docs.deepseek.com/news/news1226",
- "error": "served fallback shell for https://api-docs.deepseek.com/news/news1226 (canonical: https://api-docs.deepseek.com/)"
+ "title": "🚀 Introducing DeepSeek-V3"
},
"content/en/news/news250325.md": {
"url": "https://api-docs.deepseek.com/news/news250325",
- "error": "served fallback shell for https://api-docs.deepseek.com/news/news250325 (canonical: https://api-docs.deepseek.com/)"
+ "title": "DeepSeek-V3-0324 Release"
},
"content/en/news/news0725.md": {
"url": "https://api-docs.deepseek.com/news/news0725",
diff --git a/content/en/api/create-chat-completion.md b/content/en/api/create-chat-completion.md
index 99fa59e..1b2a404 100644
--- a/content/en/api/create-chat-completion.md
+++ b/content/en/api/create-chat-completion.md
@@ -2,7 +2,7 @@
title: "Chat Completions API"
description: "Creates a model response for the given chat conversation."
source: https://api-docs.deepseek.com/api/create-chat-completion
-fetched: 2026-08-23
+fetched: 2026-08-26
---
# Chat Completions API
@@ -260,7 +260,9 @@ Options for streaming response. Only set this when you set `stream: true`.
**include\_usage** boolean
-If set, an additional chunk will be streamed before the `data: [DONE]` message. The `usage` field on this chunk shows the token usage statistics for the entire request, and the `choices` field will always be an empty array. All other chunks will also include a `usage` field, but with a null value.
+If set to `true`, all chunks in the stream will include a `usage` field, whose value is `null` on every chunk except the last one. If omitted or set to `false`, the `usage` field is absent from all chunks except the last one.
+
+Either way, the last chunk before the `data: [DONE]` message carries the token usage statistics for the entire request in its `usage` field. Note that no separate usage-only chunk is emitted: the statistics ride on the last content chunk, whose `choices` array always contains exactly one element that carries no new content and a non-null `finish_reason`.
**temperature** numbernullable
diff --git a/content/en/api/create-completion.md b/content/en/api/create-completion.md
index 9fae84c..a3948c2 100644
--- a/content/en/api/create-completion.md
+++ b/content/en/api/create-completion.md
@@ -2,7 +2,7 @@
title: "FIM Completion API (Beta)"
description: "FIM (Fill In the Middle) Completion API.
User must set `base_url='https://api.deepseek.com/beta'` to use this feature."
source: https://api-docs.deepseek.com/api/create-completion
-fetched: 2026-08-02
+fetched: 2026-08-26
---
# FIM Completion API (Beta)
@@ -79,7 +79,9 @@ Options for streaming response. Only set this when you set `stream: true`.
**include\_usage** boolean
-If set, an additional chunk will be streamed before the `data: [DONE]` message. The `usage` field on this chunk shows the token usage statistics for the entire request, and the `choices` field will always be an empty array. All other chunks will also include a `usage` field, but with a null value.
+If set to `true`, all chunks in the stream will include a `usage` field, whose value is `null` on every chunk except the last one. If omitted or set to `false`, the `usage` field is absent from all chunks except the last one.
+
+Either way, the last chunk before the `data: [DONE]` message carries the token usage statistics for the entire request in its `usage` field. Note that no separate usage-only chunk is emitted: the statistics ride on the last content chunk, whose `choices` array always contains exactly one element that carries no new content and a non-null `finish_reason`.
**suffix** stringnullable
diff --git a/content/zh-cn/api/create-chat-completion.md b/content/zh-cn/api/create-chat-completion.md
index 7b1bea5..009376c 100644
--- a/content/zh-cn/api/create-chat-completion.md
+++ b/content/zh-cn/api/create-chat-completion.md
@@ -2,7 +2,7 @@
title: "Chat Completions API"
description: "根据输入的上下文，来让模型补全对话内容。"
source: https://api-docs.deepseek.com/zh-cn/api/create-chat-completion
-fetched: 2026-08-23
+fetched: 2026-08-26
---
# Chat Completions API
@@ -258,7 +258,9 @@ string
**include\_usage** boolean
-如果设置为 true，在流式消息最后的 `data: [DONE]` 之前将会传输一个额外的块。此块上的 usage 字段显示整个请求的 token 使用统计信息，而 choices 字段将始终是一个空数组。所有其他块也将包含一个 usage 字段，但其值为 null。
+如果设置为 `true`，流式返回的所有块都会包含 `usage` 字段，其中除最后一个块外，该字段的值均为 `null`。如果不设置或设置为 `false`，则除最后一个块外，其余块都不含 `usage` 字段。
+
+无论是否设置，`data: [DONE]` 之前的最后一个块都会在其 `usage` 字段中给出整个请求的 token 使用统计信息。请注意，这里不会单独下发一个只含 usage 的块：统计信息附加在最后一个内容块上，该块的 `choices` 数组始终只包含一个元素，其中不含新增内容且 `finish_reason` 非 null。
**temperature** numbernullable
diff --git a/content/zh-cn/api/create-completion.md b/content/zh-cn/api/create-completion.md
index fe20b7f..36e2825 100644
--- a/content/zh-cn/api/create-completion.md
+++ b/content/zh-cn/api/create-completion.md
@@ -2,7 +2,7 @@
title: "FIM 补全 API（Beta）"
description: "FIM (Fill In the Middle) 补全 API。
用户需要设置 `base_url='https://api.deepseek.com/beta'` 来使用此功能。"
source: https://api-docs.deepseek.com/zh-cn/api/create-completion
-fetched: 2026-08-23
+fetched: 2026-08-26
---
# FIM 补全 API（Beta）
@@ -79,7 +79,9 @@ string
**include\_usage** boolean
-如果设置为 true，在流式消息最后的 `data: [DONE]` 之前将会传输一个额外的块。此块上的 usage 字段显示整个请求的 token 使用统计信息，而 choices 字段将始终是一个空数组。所有其他块也将包含一个 usage 字段，但其值为 null。
+如果设置为 `true`，流式返回的所有块都会包含 `usage` 字段，其中除最后一个块外，该字段的值均为 `null`。如果不设置或设置为 `false`，则除最后一个块外，其余块都不含 `usage` 字段。
+
+无论是否设置，`data: [DONE]` 之前的最后一个块都会在其 `usage` 字段中给出整个请求的 token 使用统计信息。请注意，这里不会单独下发一个只含 usage 的块：统计信息附加在最后一个内容块上，该块的 `choices` 数组始终只包含一个元素，其中不含新增内容且 `finish_reason` 非 null。
**suffix** stringnullable
diff --git a/llms-full.txt b/llms-full.txt
index 41f4155..4097750 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -7,7 +7,7 @@
title: "Chat Completions API"
description: "Creates a model response for the given chat conversation."
source: https://api-docs.deepseek.com/api/create-chat-completion
-fetched: 2026-08-23
+fetched: 2026-08-26
---
# Chat Completions API
@@ -265,7 +265,9 @@ Options for streaming response. Only set this when you set `stream: true`.
**include\_usage** boolean
-If set, an additional chunk will be streamed before the `data: [DONE]` message. The `usage` field on this chunk shows the token usage statistics for the entire request, and the `choices` field will always be an empty array. All other chunks will also include a `usage` field, but with a null value.
+If set to `true`, all chunks in the stream will include a `usage` field, whose value is `null` on every chunk except the last one. If omitted or set to `false`, the `usage` field is absent from all chunks except the last one.
+
+Either way, the last chunk before the `data: [DONE]` message carries the token usage statistics for the entire request in its `usage` field. Note that no separate usage-only chunk is emitted: the statistics ride on the last content chunk, whose `choices` array always contains exactly one element that carries no new content and a non-null `finish_reason`.
**temperature** numbernullable
@@ -990,7 +992,7 @@ Loading...
title: "FIM Completion API (Beta)"
description: "FIM (Fill In the Middle) Completion API.
User must set `base_url='https://api.deepseek.com/beta'` to use this feature."
source: https://api-docs.deepseek.com/api/create-completion
-fetched: 2026-08-02
+fetched: 2026-08-26
---
# FIM Completion API (Beta)
@@ -1067,7 +1069,9 @@ Options for streaming response. Only set this when you set `stream: true`.
**include\_usage** boolean
-If set, an additional chunk will be streamed before the `data: [DONE]` message. The `usage` field on this chunk shows the token usage statistics for the entire request, and the `choices` field will always be an empty array. All other chunks will also include a `usage` field, but with a null value.
+If set to `true`, all chunks in the stream will include a `usage` field, whose value is `null` on every chunk except the last one. If omitted or set to `false`, the `usage` field is absent from all chunks except the last one.
+
+Either way, the last chunk before the `data: [DONE]` message carries the token usage statistics for the entire request in its `usage` field. Note that no separate usage-only chunk is emitted: the statistics ride on the last content chunk, whose `choices` array always contains exactly one element that carries no new content and a non-null `finish_reason`.
**suffix** stringnullable