docs: clarify Voice expire_time and store TTL behavior in GAOS SDK

PiperOrigin-RevId: 990686007

Author: google-genai-bot

google/genai/_gaos/types/voices/createvoicerequest.py

@@ -37,9 +37,11 @@ class CreateVoiceRequestParam(TypedDict):
 
     * When `true`, Google stores the voice and returns `Voice.id` (for example,
     `voice_abc123def456`), which can be managed via `GetVoice`, `ListVoices`,
-    and `DeleteVoice` and referenced by ID in synthesis requests. Projects
-    are subject to a maximum active stored voice quota; exceeding the quota
-    returns `RESOURCE_EXHAUSTED`.
+    and `DeleteVoice` and referenced by ID in synthesis requests. Stored
+    voices expire after 1 year of inactivity; using a stored voice in speech
+    synthesis or as a `base_voice` in `CreateVoice` extends its
+    `expire_time`. Projects are subject to a maximum active stored voice
+    quota; exceeding the quota returns `RESOURCE_EXHAUSTED`.
     * When `false` (default), the voice is not stored by Google and `Voice.key`
     (for example, `voicekey_...`) is returned for client-side storage and
     synthesis. Optional discovery metadata fields on `voice` are not
@@ -62,9 +64,11 @@ class CreateVoiceRequest(BaseModel):
 
     * When `true`, Google stores the voice and returns `Voice.id` (for example,
     `voice_abc123def456`), which can be managed via `GetVoice`, `ListVoices`,
-    and `DeleteVoice` and referenced by ID in synthesis requests. Projects
-    are subject to a maximum active stored voice quota; exceeding the quota
-    returns `RESOURCE_EXHAUSTED`.
+    and `DeleteVoice` and referenced by ID in synthesis requests. Stored
+    voices expire after 1 year of inactivity; using a stored voice in speech
+    synthesis or as a `base_voice` in `CreateVoice` extends its
+    `expire_time`. Projects are subject to a maximum active stored voice
+    quota; exceeding the quota returns `RESOURCE_EXHAUSTED`.
     * When `false` (default), the voice is not stored by Google and `Voice.key`
     (for example, `voicekey_...`) is returned for client-side storage and
     synthesis. Optional discovery metadata fields on `voice` are not

google/genai/_gaos/types/voices/voice_output.py

@@ -50,8 +50,10 @@ class VoiceOutputTypedDict(TypedDict):
     """
     expire_time: NotRequired[datetime]
     r"""Output only. The timestamp at which a custom stored voice (`store = true`)
-    or replicated voice key (`store = false`) expires. Unset for prebuilt
-    catalog voices (`\"prebuilt\"`), which do not expire.
+    or replicated voice key (`store = false`) expires. For custom stored voices
+    (`store = true`), this expiration time is extended when the voice is used
+    for speech synthesis or as a `base_voice` in `CreateVoice`. Unset for
+    prebuilt catalog voices (`\"prebuilt\"`), which do not expire.
     """
     gender: NotRequired[str]
     r"""Optional. Perceived voice gender presentation (e.g. \"female\", \"male\",
@@ -130,8 +132,10 @@ class VoiceOutput(BaseModel):
 
     expire_time: Optional[datetime] = None
     r"""Output only. The timestamp at which a custom stored voice (`store = true`)
-    or replicated voice key (`store = false`) expires. Unset for prebuilt
-    catalog voices (`\"prebuilt\"`), which do not expire.
+    or replicated voice key (`store = false`) expires. For custom stored voices
+    (`store = true`), this expiration time is extended when the voice is used
+    for speech synthesis or as a `base_voice` in `CreateVoice`. Unset for
+    prebuilt catalog voices (`\"prebuilt\"`), which do not expire.
     """
 
     gender: Optional[str] = None

google/genai/_gaos/voices.py

@@ -268,9 +268,11 @@ def create(
 
             * When `true`, Google stores the voice and returns `Voice.id` (for example,
             `voice_abc123def456`), which can be managed via `GetVoice`, `ListVoices`,
-            and `DeleteVoice` and referenced by ID in synthesis requests. Projects
-            are subject to a maximum active stored voice quota; exceeding the quota
-            returns `RESOURCE_EXHAUSTED`.
+            and `DeleteVoice` and referenced by ID in synthesis requests. Stored
+            voices expire after 1 year of inactivity; using a stored voice in speech
+            synthesis or as a `base_voice` in `CreateVoice` extends its
+            `expire_time`. Projects are subject to a maximum active stored voice
+            quota; exceeding the quota returns `RESOURCE_EXHAUSTED`.
             * When `false` (default), the voice is not stored by Google and `Voice.key`
             (for example, `voicekey_...`) is returned for client-side storage and
             synthesis. Optional discovery metadata fields on `voice` are not
@@ -1005,9 +1007,11 @@ async def create(
 
             * When `true`, Google stores the voice and returns `Voice.id` (for example,
             `voice_abc123def456`), which can be managed via `GetVoice`, `ListVoices`,
-            and `DeleteVoice` and referenced by ID in synthesis requests. Projects
-            are subject to a maximum active stored voice quota; exceeding the quota
-            returns `RESOURCE_EXHAUSTED`.
+            and `DeleteVoice` and referenced by ID in synthesis requests. Stored
+            voices expire after 1 year of inactivity; using a stored voice in speech
+            synthesis or as a `base_voice` in `CreateVoice` extends its
+            `expire_time`. Projects are subject to a maximum active stored voice
+            quota; exceeding the quota returns `RESOURCE_EXHAUSTED`.
             * When `false` (default), the voice is not stored by Google and `Voice.key`
             (for example, `voicekey_...`) is returned for client-side storage and
             synthesis. Optional discovery metadata fields on `voice` are not