From 45b4963f4cdc8dc01cffe85260c629e50595fbf9 Mon Sep 17 00:00:00 2001 From: Jaycee Li Date: Thu, 4 Jun 2026 10:51:26 -0700 Subject: [PATCH] feat: Add ServiceTier to UsageMetadata PiperOrigin-RevId: 926773736 --- google/genai/types.py | 143 ++++++++++++++++++++++++------------------ 1 file changed, 81 insertions(+), 62 deletions(-) diff --git a/google/genai/types.py b/google/genai/types.py index 12721ad1c..f99fbd070 100644 --- a/google/genai/types.py +++ b/google/genai/types.py @@ -561,19 +561,21 @@ class TrafficType(_common.CaseInSensitiveEnum): """Type for Provisioned Throughput traffic.""" -class Modality(_common.CaseInSensitiveEnum): - """Server content modalities.""" +class MediaModality(_common.CaseInSensitiveEnum): + """The modality that this token count applies to.""" MODALITY_UNSPECIFIED = 'MODALITY_UNSPECIFIED' - """The modality is unspecified.""" + """When a modality is not specified, it is treated as `TEXT`.""" TEXT = 'TEXT' - """Indicates the model should return text""" + """The `Part` contains plain text.""" IMAGE = 'IMAGE' - """Indicates the model should return images.""" - AUDIO = 'AUDIO' - """Indicates the model should return audio.""" + """The `Part` contains an image.""" VIDEO = 'VIDEO' - """Indicates the model should return video.""" + """The `Part` contains a video.""" + AUDIO = 'AUDIO' + """The `Part` contains audio.""" + DOCUMENT = 'DOCUMENT' + """The `Part` contains a document, such as a PDF.""" class ModelStage(_common.CaseInSensitiveEnum): @@ -613,6 +615,21 @@ class MediaResolution(_common.CaseInSensitiveEnum): """Media resolution set to high (zoomed reframing with 256 tokens).""" +class Modality(_common.CaseInSensitiveEnum): + """Server content modalities.""" + + MODALITY_UNSPECIFIED = 'MODALITY_UNSPECIFIED' + """The modality is unspecified.""" + TEXT = 'TEXT' + """Indicates the model should return text""" + IMAGE = 'IMAGE' + """Indicates the model should return images.""" + AUDIO = 'AUDIO' + """Indicates the model should return audio.""" + VIDEO = 'VIDEO' + """Indicates the model should return video.""" + + class TuningMode(_common.CaseInSensitiveEnum): """Tuning mode. This enum is not supported in Gemini API.""" @@ -795,6 +812,19 @@ class DocumentState(_common.CaseInSensitiveEnum): """Some `Chunks` of the `Document` failed processing.""" +class ServiceTier(_common.CaseInSensitiveEnum): + """Pricing and performance service tier.""" + + UNSPECIFIED = 'unspecified' + """Default service tier, which is standard.""" + FLEX = 'flex' + """Flex service tier.""" + STANDARD = 'standard' + """Standard service tier.""" + PRIORITY = 'priority' + """Priority service tier.""" + + class RubricContentType(_common.CaseInSensitiveEnum): """Represents the rubric content type.""" @@ -866,19 +896,6 @@ class ResourceScope(_common.CaseInSensitiveEnum): "https://aiplatform.googleapis.com/publishers/google/models/gemini-3-pro-preview""" -class ServiceTier(_common.CaseInSensitiveEnum): - """Pricing and performance service tier.""" - - UNSPECIFIED = 'unspecified' - """Default service tier, which is standard.""" - FLEX = 'flex' - """Flex service tier.""" - STANDARD = 'standard' - """Standard service tier.""" - PRIORITY = 'priority' - """Priority service tier.""" - - class JSONSchemaType(Enum): """The type of the data supported by JSON Schema. @@ -1185,23 +1202,6 @@ class TurnCompleteReason(_common.CaseInSensitiveEnum): """Max regeneration attempts reached.""" -class MediaModality(_common.CaseInSensitiveEnum): - """Server content modalities.""" - - MODALITY_UNSPECIFIED = 'MODALITY_UNSPECIFIED' - """The modality is unspecified.""" - TEXT = 'TEXT' - """Plain text.""" - IMAGE = 'IMAGE' - """Images.""" - VIDEO = 'VIDEO' - """Video.""" - AUDIO = 'AUDIO' - """Audio.""" - DOCUMENT = 'DOCUMENT' - """Document, e.g. PDF.""" - - class VadSignalType(_common.CaseInSensitiveEnum): """The type of the VAD signal.""" @@ -7846,11 +7846,18 @@ class GenerateContentResponsePromptFeedbackDict(TypedDict, total=False): class ModalityTokenCount(_common.BaseModel): - """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. + """ modality: Optional[MediaModality] = Field( default=None, - description="""The modality associated with this token count.""", + description="""The modality that this token count applies to.""", ) token_count: Optional[int] = Field( default=None, @@ -7859,10 +7866,17 @@ class ModalityTokenCount(_common.BaseModel): class ModalityTokenCountDict(TypedDict, total=False): - """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. + """ modality: Optional[MediaModality] - """The modality associated with this token count.""" + """The modality that this token count applies to.""" token_count: Optional[int] """The number of tokens counted for this modality.""" @@ -19442,11 +19456,11 @@ class UsageMetadata(_common.BaseModel): prompt_token_count: Optional[int] = Field( default=None, - description="""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.""", + description="""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.""", ) cached_content_token_count: Optional[int] = Field( default=None, - description="""Number of tokens in the cached part of the prompt (the cached content).""", + description="""Output only. The number of tokens in the cached content that was used for this request.""", ) response_token_count: Optional[int] = Field( default=None, @@ -19454,23 +19468,23 @@ class UsageMetadata(_common.BaseModel): ) tool_use_prompt_token_count: Optional[int] = Field( default=None, - description="""Number of tokens present in tool-use prompt(s).""", + description="""Output only. The number of tokens in the results from tool executions, which are provided back to the model as input, if applicable.""", ) thoughts_token_count: Optional[int] = Field( default=None, - description="""Number of tokens of thoughts for thinking models.""", + description="""Output only. The number of tokens that were part of the model's generated "thoughts" output, if applicable.""", ) total_token_count: Optional[int] = Field( default=None, - description="""Total token count for prompt, response candidates, and tool-use prompts(if present).""", + description="""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`.""", ) prompt_tokens_details: Optional[list[ModalityTokenCount]] = Field( default=None, - description="""List of modalities that were processed in the request input.""", + description="""Output only. A detailed breakdown of the token count for each modality in the prompt.""", ) cache_tokens_details: Optional[list[ModalityTokenCount]] = Field( default=None, - description="""List of modalities that were processed in the cache input.""", + description="""Output only. A detailed breakdown of the token count for each modality in the cached content.""", ) response_tokens_details: Optional[list[ModalityTokenCount]] = Field( default=None, @@ -19478,12 +19492,15 @@ class UsageMetadata(_common.BaseModel): ) tool_use_prompt_tokens_details: Optional[list[ModalityTokenCount]] = Field( default=None, - description="""List of modalities that were processed in the tool-use prompt.""", + description="""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.""", ) traffic_type: Optional[TrafficType] = Field( default=None, - description="""Traffic type. This shows whether a request consumes Pay-As-You-Go - or Provisioned Throughput quota.""", + description="""Output only. The traffic type for this request. This field is not supported in Gemini API.""", + ) + service_tier: Optional[ServiceTier] = Field( + default=None, + description="""Output only. Service tier of the request. This field is not supported in Vertex AI.""", ) @@ -19491,38 +19508,40 @@ class UsageMetadataDict(TypedDict, total=False): """Usage metadata about response(s).""" prompt_token_count: Optional[int] - """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.""" cached_content_token_count: Optional[int] - """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.""" response_token_count: Optional[int] """Total number of tokens across all the generated response candidates.""" tool_use_prompt_token_count: Optional[int] - """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.""" thoughts_token_count: Optional[int] - """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.""" total_token_count: Optional[int] - """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`.""" prompt_tokens_details: Optional[list[ModalityTokenCountDict]] - """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.""" cache_tokens_details: Optional[list[ModalityTokenCountDict]] - """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.""" response_tokens_details: Optional[list[ModalityTokenCountDict]] """List of modalities that were returned in the response.""" tool_use_prompt_tokens_details: Optional[list[ModalityTokenCountDict]] - """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.""" traffic_type: Optional[TrafficType] - """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.""" + + service_tier: Optional[ServiceTier] + """Output only. Service tier of the request. This field is not supported in Vertex AI.""" UsageMetadataOrDict = Union[UsageMetadata, UsageMetadataDict]