feat: Add ServiceTier to UsageMetadata

PiperOrigin-RevId: 926773736

Author: jaycee-li

src/main/java/com/google/genai/types/MediaModality.java

@@ -23,27 +23,27 @@
 import com.google.common.base.Ascii;
 import java.util.Objects;
 
-/** Server content modalities. */
+/** The modality that this token count applies to. */
 public class MediaModality {
 
   /** Enum representing the known values for MediaModality. */
   public enum Known {
-    /** The modality is unspecified. */
+    /** When a modality is not specified, it is treated as `TEXT`. */
     MODALITY_UNSPECIFIED,
 
-    /** Plain text. */
+    /** The `Part` contains plain text. */
     TEXT,
 
-    /** Images. */
+    /** The `Part` contains an image. */
     IMAGE,
 
-    /** Video. */
+    /** The `Part` contains a video. */
     VIDEO,
 
-    /** Audio. */
+    /** The `Part` contains audio. */
     AUDIO,
 
-    /** Document, e.g. PDF. */
+    /** The `Part` contains a document, such as a PDF. */
     DOCUMENT,
 
     MEDIA_MODALITY_UNSPECIFIED

src/main/java/com/google/genai/types/ModalityTokenCount.java

@@ -26,11 +26,17 @@
 import com.google.genai.JsonSerializable;
 import java.util.Optional;
 
-/** Represents token counting info for a single modality. */
+/**
+ * Represents a breakdown of token usage by modality. This message is used in CountTokensResponse
+ * and GenerateContentResponse.UsageMetadata to provide a detailed view of how many tokens are used
+ * by each modality (e.g., text, image, video) in a request. This is particularly useful for
+ * multimodal models, allowing you to track and manage token consumption for billing and quota
+ * purposes.
+ */
 @AutoValue
 @JsonDeserialize(builder = ModalityTokenCount.Builder.class)
 public abstract class ModalityTokenCount extends JsonSerializable {
-  /** The modality associated with this token count. */
+  /** The modality that this token count applies to. */
   @JsonProperty("modality")
   public abstract Optional<MediaModality> modality();
 
@@ -59,7 +65,7 @@ private static Builder create() {
     /**
      * Setter for modality.
      *
-     * <p>modality: The modality associated with this token count.
+     * <p>modality: The modality that this token count applies to.
      */
     @JsonProperty("modality")
     public abstract Builder modality(MediaModality modality);
@@ -77,7 +83,7 @@ public Builder clearModality() {
     /**
      * Setter for modality given a known enum.
      *
-     * <p>modality: The modality associated with this token count.
+     * <p>modality: The modality that this token count applies to.
      */
     @CanIgnoreReturnValue
     public Builder modality(MediaModality.Known knownType) {
@@ -87,7 +93,7 @@ public Builder modality(MediaModality.Known knownType) {
     /**
      * Setter for modality given a string.
      *
-     * <p>modality: The modality associated with this token count.
+     * <p>modality: The modality that this token count applies to.
      */
     @CanIgnoreReturnValue
     public Builder modality(String modality) {

src/main/java/com/google/genai/types/UsageMetadata.java

@@ -35,55 +35,71 @@
 @JsonDeserialize(builder = UsageMetadata.Builder.class)
 public abstract class UsageMetadata extends JsonSerializable {
   /**
-   * Number of tokens in the prompt. When `cached_content` is set, this is still the total effective
-   * prompt size meaning this includes the number of tokens in the cached content.
+   * The total number of tokens in the prompt. This includes any text, images, or other media
+   * provided in the request. When `cached_content` is set, this also includes the number of tokens
+   * in the cached content.
    */
   @JsonProperty("promptTokenCount")
   public abstract Optional<Integer> promptTokenCount();
 
-  /** Number of tokens in the cached part of the prompt (the cached content). */
+  /** Output only. The number of tokens in the cached content that was used for this request. */
   @JsonProperty("cachedContentTokenCount")
   public abstract Optional<Integer> cachedContentTokenCount();
 
   /** Total number of tokens across all the generated response candidates. */
   @JsonProperty("responseTokenCount")
   public abstract Optional<Integer> responseTokenCount();
 
-  /** Number of tokens present in tool-use prompt(s). */
+  /**
+   * Output only. The number of tokens in the results from tool executions, which are provided back
+   * to the model as input, if applicable.
+   */
   @JsonProperty("toolUsePromptTokenCount")
   public abstract Optional<Integer> toolUsePromptTokenCount();
 
-  /** Number of tokens of thoughts for thinking models. */
+  /**
+   * Output only. The number of tokens that were part of the model's generated "thoughts" output, if
+   * applicable.
+   */
   @JsonProperty("thoughtsTokenCount")
   public abstract Optional<Integer> thoughtsTokenCount();
 
-  /** Total token count for prompt, response candidates, and tool-use prompts(if present). */
+  /**
+   * The total number of tokens for the entire request. This is the sum of `prompt_token_count`,
+   * `candidates_token_count`, `tool_use_prompt_token_count`, and `thoughts_token_count`.
+   */
   @JsonProperty("totalTokenCount")
   public abstract Optional<Integer> totalTokenCount();
 
-  /** List of modalities that were processed in the request input. */
+  /** Output only. A detailed breakdown of the token count for each modality in the prompt. */
   @JsonProperty("promptTokensDetails")
   public abstract Optional<List<ModalityTokenCount>> promptTokensDetails();
 
-  /** List of modalities that were processed in the cache input. */
+  /**
+   * Output only. A detailed breakdown of the token count for each modality in the cached content.
+   */
   @JsonProperty("cacheTokensDetails")
   public abstract Optional<List<ModalityTokenCount>> cacheTokensDetails();
 
   /** List of modalities that were returned in the response. */
   @JsonProperty("responseTokensDetails")
   public abstract Optional<List<ModalityTokenCount>> responseTokensDetails();
 
-  /** List of modalities that were processed in the tool-use prompt. */
+  /**
+   * Output only. A detailed breakdown by modality of the token counts from the results of tool
+   * executions, which are provided back to the model as input.
+   */
   @JsonProperty("toolUsePromptTokensDetails")
   public abstract Optional<List<ModalityTokenCount>> toolUsePromptTokensDetails();
 
-  /**
-   * Traffic type. This shows whether a request consumes Pay-As-You-Go or Provisioned Throughput
-   * quota.
-   */
+  /** Output only. The traffic type for this request. This field is not supported in Gemini API. */
   @JsonProperty("trafficType")
   public abstract Optional<TrafficType> trafficType();
 
+  /** Output only. Service tier of the request. This field is not supported in Vertex AI. */
+  @JsonProperty("serviceTier")
+  public abstract Optional<ServiceTier> serviceTier();
+
   /** Instantiates a builder for UsageMetadata. */
   @ExcludeFromGeneratedCoverageReport
   public static Builder builder() {
@@ -105,9 +121,9 @@ private static Builder create() {
     /**
      * Setter for promptTokenCount.
      *
-     * <p>promptTokenCount: Number of tokens in the prompt. When `cached_content` is set, this is
-     * still the total effective prompt size meaning this includes the number of tokens in the
-     * cached content.
+     * <p>promptTokenCount: The total number of tokens in the prompt. This includes any text,
+     * images, or other media provided in the request. When `cached_content` is set, this also
+     * includes the number of tokens in the cached content.
      */
     @JsonProperty("promptTokenCount")
     public abstract Builder promptTokenCount(Integer promptTokenCount);
@@ -125,8 +141,8 @@ public Builder clearPromptTokenCount() {
     /**
      * Setter for cachedContentTokenCount.
      *
-     * <p>cachedContentTokenCount: Number of tokens in the cached part of the prompt (the cached
-     * content).
+     * <p>cachedContentTokenCount: Output only. The number of tokens in the cached content that was
+     * used for this request.
      */
     @JsonProperty("cachedContentTokenCount")
     public abstract Builder cachedContentTokenCount(Integer cachedContentTokenCount);
@@ -162,7 +178,8 @@ public Builder clearResponseTokenCount() {
     /**
      * Setter for toolUsePromptTokenCount.
      *
-     * <p>toolUsePromptTokenCount: Number of tokens present in tool-use prompt(s).
+     * <p>toolUsePromptTokenCount: Output only. The number of tokens in the results from tool
+     * executions, which are provided back to the model as input, if applicable.
      */
     @JsonProperty("toolUsePromptTokenCount")
     public abstract Builder toolUsePromptTokenCount(Integer toolUsePromptTokenCount);
@@ -180,7 +197,8 @@ public Builder clearToolUsePromptTokenCount() {
     /**
      * Setter for thoughtsTokenCount.
      *
-     * <p>thoughtsTokenCount: Number of tokens of thoughts for thinking models.
+     * <p>thoughtsTokenCount: Output only. The number of tokens that were part of the model's
+     * generated "thoughts" output, if applicable.
      */
     @JsonProperty("thoughtsTokenCount")
     public abstract Builder thoughtsTokenCount(Integer thoughtsTokenCount);
@@ -198,8 +216,9 @@ public Builder clearThoughtsTokenCount() {
     /**
      * Setter for totalTokenCount.
      *
-     * <p>totalTokenCount: Total token count for prompt, response candidates, and tool-use
-     * prompts(if present).
+     * <p>totalTokenCount: The total number of tokens for the entire request. This is the sum of
+     * `prompt_token_count`, `candidates_token_count`, `tool_use_prompt_token_count`, and
+     * `thoughts_token_count`.
      */
     @JsonProperty("totalTokenCount")
     public abstract Builder totalTokenCount(Integer totalTokenCount);
@@ -217,15 +236,17 @@ public Builder clearTotalTokenCount() {
     /**
      * Setter for promptTokensDetails.
      *
-     * <p>promptTokensDetails: List of modalities that were processed in the request input.
+     * <p>promptTokensDetails: Output only. A detailed breakdown of the token count for each
+     * modality in the prompt.
      */
     @JsonProperty("promptTokensDetails")
     public abstract Builder promptTokensDetails(List<ModalityTokenCount> promptTokensDetails);
 
     /**
      * Setter for promptTokensDetails.
      *
-     * <p>promptTokensDetails: List of modalities that were processed in the request input.
+     * <p>promptTokensDetails: Output only. A detailed breakdown of the token count for each
+     * modality in the prompt.
      */
     @CanIgnoreReturnValue
     public Builder promptTokensDetails(ModalityTokenCount... promptTokensDetails) {
@@ -235,7 +256,8 @@ public Builder promptTokensDetails(ModalityTokenCount... promptTokensDetails) {
     /**
      * Setter for promptTokensDetails builder.
      *
-     * <p>promptTokensDetails: List of modalities that were processed in the request input.
+     * <p>promptTokensDetails: Output only. A detailed breakdown of the token count for each
+     * modality in the prompt.
      */
     @CanIgnoreReturnValue
     public Builder promptTokensDetails(ModalityTokenCount.Builder... promptTokensDetailsBuilders) {
@@ -258,15 +280,17 @@ public Builder clearPromptTokensDetails() {
     /**
      * Setter for cacheTokensDetails.
      *
-     * <p>cacheTokensDetails: List of modalities that were processed in the cache input.
+     * <p>cacheTokensDetails: Output only. A detailed breakdown of the token count for each modality
+     * in the cached content.
      */
     @JsonProperty("cacheTokensDetails")
     public abstract Builder cacheTokensDetails(List<ModalityTokenCount> cacheTokensDetails);
 
     /**
      * Setter for cacheTokensDetails.
      *
-     * <p>cacheTokensDetails: List of modalities that were processed in the cache input.
+     * <p>cacheTokensDetails: Output only. A detailed breakdown of the token count for each modality
+     * in the cached content.
      */
     @CanIgnoreReturnValue
     public Builder cacheTokensDetails(ModalityTokenCount... cacheTokensDetails) {
@@ -276,7 +300,8 @@ public Builder cacheTokensDetails(ModalityTokenCount... cacheTokensDetails) {
     /**
      * Setter for cacheTokensDetails builder.
      *
-     * <p>cacheTokensDetails: List of modalities that were processed in the cache input.
+     * <p>cacheTokensDetails: Output only. A detailed breakdown of the token count for each modality
+     * in the cached content.
      */
     @CanIgnoreReturnValue
     public Builder cacheTokensDetails(ModalityTokenCount.Builder... cacheTokensDetailsBuilders) {
@@ -342,7 +367,8 @@ public Builder clearResponseTokensDetails() {
     /**
      * Setter for toolUsePromptTokensDetails.
      *
-     * <p>toolUsePromptTokensDetails: List of modalities that were processed in the tool-use prompt.
+     * <p>toolUsePromptTokensDetails: Output only. A detailed breakdown by modality of the token
+     * counts from the results of tool executions, which are provided back to the model as input.
      */
     @JsonProperty("toolUsePromptTokensDetails")
     public abstract Builder toolUsePromptTokensDetails(
@@ -351,7 +377,8 @@ public abstract Builder toolUsePromptTokensDetails(
     /**
      * Setter for toolUsePromptTokensDetails.
      *
-     * <p>toolUsePromptTokensDetails: List of modalities that were processed in the tool-use prompt.
+     * <p>toolUsePromptTokensDetails: Output only. A detailed breakdown by modality of the token
+     * counts from the results of tool executions, which are provided back to the model as input.
      */
     @CanIgnoreReturnValue
     public Builder toolUsePromptTokensDetails(ModalityTokenCount... toolUsePromptTokensDetails) {
@@ -361,7 +388,8 @@ public Builder toolUsePromptTokensDetails(ModalityTokenCount... toolUsePromptTok
     /**
      * Setter for toolUsePromptTokensDetails builder.
      *
-     * <p>toolUsePromptTokensDetails: List of modalities that were processed in the tool-use prompt.
+     * <p>toolUsePromptTokensDetails: Output only. A detailed breakdown by modality of the token
+     * counts from the results of tool executions, which are provided back to the model as input.
      */
     @CanIgnoreReturnValue
     public Builder toolUsePromptTokensDetails(
@@ -386,8 +414,8 @@ public Builder clearToolUsePromptTokensDetails() {
     /**
      * Setter for trafficType.
      *
-     * <p>trafficType: Traffic type. This shows whether a request consumes Pay-As-You-Go or
-     * Provisioned Throughput quota.
+     * <p>trafficType: Output only. The traffic type for this request. This field is not supported
+     * in Gemini API.
      */
     @JsonProperty("trafficType")
     public abstract Builder trafficType(TrafficType trafficType);
@@ -405,8 +433,8 @@ public Builder clearTrafficType() {
     /**
      * Setter for trafficType given a known enum.
      *
-     * <p>trafficType: Traffic type. This shows whether a request consumes Pay-As-You-Go or
-     * Provisioned Throughput quota.
+     * <p>trafficType: Output only. The traffic type for this request. This field is not supported
+     * in Gemini API.
      */
     @CanIgnoreReturnValue
     public Builder trafficType(TrafficType.Known knownType) {
@@ -416,14 +444,55 @@ public Builder trafficType(TrafficType.Known knownType) {
     /**
      * Setter for trafficType given a string.
      *
-     * <p>trafficType: Traffic type. This shows whether a request consumes Pay-As-You-Go or
-     * Provisioned Throughput quota.
+     * <p>trafficType: Output only. The traffic type for this request. This field is not supported
+     * in Gemini API.
      */
     @CanIgnoreReturnValue
     public Builder trafficType(String trafficType) {
       return trafficType(new TrafficType(trafficType));
     }
 
+    /**
+     * Setter for serviceTier.
+     *
+     * <p>serviceTier: Output only. Service tier of the request. This field is not supported in
+     * Vertex AI.
+     */
+    @JsonProperty("serviceTier")
+    public abstract Builder serviceTier(ServiceTier serviceTier);
+
+    @ExcludeFromGeneratedCoverageReport
+    abstract Builder serviceTier(Optional<ServiceTier> serviceTier);
+
+    /** Clears the value of serviceTier field. */
+    @ExcludeFromGeneratedCoverageReport
+    @CanIgnoreReturnValue
+    public Builder clearServiceTier() {
+      return serviceTier(Optional.empty());
+    }
+
+    /**
+     * Setter for serviceTier given a known enum.
+     *
+     * <p>serviceTier: Output only. Service tier of the request. This field is not supported in
+     * Vertex AI.
+     */
+    @CanIgnoreReturnValue
+    public Builder serviceTier(ServiceTier.Known knownType) {
+      return serviceTier(new ServiceTier(knownType));
+    }
+
+    /**
+     * Setter for serviceTier given a string.
+     *
+     * <p>serviceTier: Output only. Service tier of the request. This field is not supported in
+     * Vertex AI.
+     */
+    @CanIgnoreReturnValue
+    public Builder serviceTier(String serviceTier) {
+      return serviceTier(new ServiceTier(serviceTier));
+    }
+
     public abstract UsageMetadata build();
   }