From 8b56ac717411267419df28945a7dca32c926f5d6 Mon Sep 17 00:00:00 2001
From: Daniel La Rocque <dlarocque@google.com>
Date: Tue, 10 Jun 2025 14:50:45 -0400
Subject: [PATCH] fix(ai): Add deprecation tag to `totalBillableCharacters`

---
 .changeset/old-candles-confess.md      |  5 +++++
 common/api-review/ai.api.md            |  1 +
 docs-devsite/ai.counttokensresponse.md | 11 +++++++----
 packages/ai/src/types/responses.ts     |  5 ++---
 4 files changed, 15 insertions(+), 7 deletions(-)
 create mode 100644 .changeset/old-candles-confess.md

diff --git a/.changeset/old-candles-confess.md b/.changeset/old-candles-confess.md
new file mode 100644
index 00000000000..6fbe742818f
--- /dev/null
+++ b/.changeset/old-candles-confess.md
@@ -0,0 +1,5 @@
+---
+'@firebase/ai': patch
+---
+
+Add deprecation label to `totalBillableCharacters`. `totalTokens` should be used instead.
diff --git a/common/api-review/ai.api.md b/common/api-review/ai.api.md
index 23c13688fb1..ab79447798f 100644
--- a/common/api-review/ai.api.md
+++ b/common/api-review/ai.api.md
@@ -164,6 +164,7 @@ export interface CountTokensRequest {
 // @public
 export interface CountTokensResponse {
     promptTokensDetails?: ModalityTokenCount[];
+    // @deprecated (undocumented)
     totalBillableCharacters?: number;
     totalTokens: number;
 }
diff --git a/docs-devsite/ai.counttokensresponse.md b/docs-devsite/ai.counttokensresponse.md
index 71e64d885d8..8a7181a2e03 100644
--- a/docs-devsite/ai.counttokensresponse.md
+++ b/docs-devsite/ai.counttokensresponse.md
@@ -23,7 +23,7 @@ export interface CountTokensResponse
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [promptTokensDetails](./ai.counttokensresponse.md#counttokensresponseprompttokensdetails) | [ModalityTokenCount](./ai.modalitytokencount.md#modalitytokencount_interface)<!-- -->\[\] | The breakdown, by modality, of how many tokens are consumed by the prompt. |
-|  [totalBillableCharacters](./ai.counttokensresponse.md#counttokensresponsetotalbillablecharacters) | number | The total number of billable characters counted across all instances from the request.<!-- -->This property is only supported when using the Vertex AI Gemini API ([VertexAIBackend](./ai.vertexaibackend.md#vertexaibackend_class)<!-- -->). When using the Gemini Developer API ([GoogleAIBackend](./ai.googleaibackend.md#googleaibackend_class)<!-- -->), this property is not supported and will default to 0. |
+|  [totalBillableCharacters](./ai.counttokensresponse.md#counttokensresponsetotalbillablecharacters) | number |  |
 |  [totalTokens](./ai.counttokensresponse.md#counttokensresponsetotaltokens) | number | The total number of tokens counted across all instances from the request. |
 
 ## CountTokensResponse.promptTokensDetails
@@ -38,9 +38,12 @@ promptTokensDetails?: ModalityTokenCount[];
 
 ## CountTokensResponse.totalBillableCharacters
 
-The total number of billable characters counted across all instances from the request.
-
-This property is only supported when using the Vertex AI Gemini API ([VertexAIBackend](./ai.vertexaibackend.md#vertexaibackend_class)<!-- -->). When using the Gemini Developer API ([GoogleAIBackend](./ai.googleaibackend.md#googleaibackend_class)<!-- -->), this property is not supported and will default to 0.
+> Warning: This API is now obsolete.
+> 
+> Use `totalTokens` instead. This property is undefined when using models greater than `gemini-1.5-*`<!-- -->.
+> 
+> The total number of billable characters counted across all instances from the request.
+> 
 
 <b>Signature:</b>
 
diff --git a/packages/ai/src/types/responses.ts b/packages/ai/src/types/responses.ts
index e33b8a86bd3..8072e06fd02 100644
--- a/packages/ai/src/types/responses.ts
+++ b/packages/ai/src/types/responses.ts
@@ -270,11 +270,10 @@ export interface CountTokensResponse {
    */
   totalTokens: number;
   /**
+   * @deprecated Use `totalTokens` instead. This property is undefined when using models greater than `gemini-1.5-*`.
+   *
    * The total number of billable characters counted across all instances
    * from the request.
-   *
-   * This property is only supported when using the Vertex AI Gemini API ({@link VertexAIBackend}).
-   * When using the Gemini Developer API ({@link GoogleAIBackend}), this property is not supported and will default to 0.
    */
   totalBillableCharacters?: number;
   /**