feat: Add webhook_config to batches.create() and models.generate_videos()

For dynamic per-request webhook notifications on batch jobs and video generation LROs.

PiperOrigin-RevId: 899099328

Author: MarkDaoust

google/genai/batches.py

@@ -526,6 +526,13 @@ def _CreateBatchJobConfig_to_mldev(
   if getv(from_object, ['dest']) is not None:
     raise ValueError('dest parameter is not supported in Gemini API.')
 
+  if getv(from_object, ['webhook_config']) is not None:
+    setv(
+        parent_object,
+        ['batch', 'webhookConfig'],
+        getv(from_object, ['webhook_config']),
+    )
+
   return to_object
 
 
@@ -547,6 +554,9 @@ def _CreateBatchJobConfig_to_vertex(
         ),
     )
 
+  if getv(from_object, ['webhook_config']) is not None:
+    raise ValueError('webhook_config parameter is not supported in Vertex AI.')
+
   return to_object
 
 

google/genai/models.py

@@ -2154,6 +2154,11 @@ def _GenerateVideosConfig_to_mldev(
   if getv(from_object, ['labels']) is not None:
     raise ValueError('labels parameter is not supported in Gemini API.')
 
+  if getv(from_object, ['webhook_config']) is not None:
+    setv(
+        parent_object, ['webhookConfig'], getv(from_object, ['webhook_config'])
+    )
+
   return to_object
 
 
@@ -2280,6 +2285,9 @@ def _GenerateVideosConfig_to_vertex(
   if getv(from_object, ['labels']) is not None:
     setv(parent_object, ['labels'], getv(from_object, ['labels']))
 
+  if getv(from_object, ['webhook_config']) is not None:
+    raise ValueError('webhook_config parameter is not supported in Vertex AI.')
+
   return to_object
 
 

google/genai/tests/batches/test_create.py

@@ -65,6 +65,51 @@
         exception_if_vertex='Unsupported destination',
         has_union=True,
     ),
+    pytest_helper.TestTableItem(
+        name='test_create_with_webhook_config',
+        parameters=types._CreateBatchJobParameters(
+            model=_GEMINI_MODEL,
+            src={
+                'inlined_requests': [
+                    {
+                        'contents': [
+                            {'parts': [{'text': 'say hello'}], 'role': 'user'}
+                        ]
+                    },
+                ]
+            },
+            config=types.CreateBatchJobConfig(
+                display_name=_DISPLAY_NAME,
+                webhook_config=types.WebhookConfig(
+                    uris=['https://example.com/webhook'],
+                    user_metadata={'batch_id': '123'},
+                ),
+            ),
+        ),
+        exception_if_vertex='not supported in Vertex AI',
+    ),
+    pytest_helper.TestTableItem(
+        name='test_create_with_webhook_config_dict',
+        parameters=types._CreateBatchJobParameters(
+            model=_GEMINI_MODEL,
+            src={
+                'inlined_requests': [
+                    {
+                        'contents': [
+                            {'parts': [{'text': 'say hello'}], 'role': 'user'}
+                        ]
+                    },
+                ]
+            },
+            config={
+                'display_name': _DISPLAY_NAME,
+                'webhook_config': {
+                    'uris': ['https://example.com/webhook'],
+                },
+            },
+        ),
+        exception_if_vertex='not supported in Vertex AI',
+    ),
 ]
 
 pytestmark = [

google/genai/tests/models/test_generate_videos.py

@@ -104,9 +104,7 @@
                 labels={"veo_label_key": "generate_videos"},
             ),
         ),
-        exception_if_mldev=(
-            "not supported in Gemini API"
-        ),
+        exception_if_mldev="not supported in Gemini API",
     ),
     pytest_helper.TestTableItem(
         name="test_from_text_source",
@@ -202,9 +200,7 @@
                 ),
             ),
         ),
-        exception_if_mldev=(
-            "not supported in Gemini API"
-        ),
+        exception_if_mldev="not supported in Gemini API",
     ),
     pytest_helper.TestTableItem(
         name="test_all_parameters_mldev",
@@ -253,6 +249,39 @@
             "output_gcs_uri parameter is not supported in Gemini API"
         ),
     ),
+    pytest_helper.TestTableItem(
+        name="test_with_webhook_config",
+        parameters=types._GenerateVideosParameters(
+            model=VEO_MODEL_LATEST,
+            prompt="Man with a dog",
+            config=types.GenerateVideosConfig(
+                number_of_videos=1,
+                webhook_config=types.WebhookConfig(
+                    uris=["https://example.com/webhook"],
+                    user_metadata={"job_id": "video_123"},
+                ),
+            ),
+        ),
+        exception_if_vertex=(
+            "webhook_config parameter is not supported in Vertex AI"
+        ),
+    ),
+    pytest_helper.TestTableItem(
+        name="test_with_webhook_config_dict",
+        parameters=types._GenerateVideosParameters(
+            model=VEO_MODEL_LATEST,
+            prompt="Man with a dog",
+            config={
+                "number_of_videos": 1,
+                "webhook_config": {
+                    "uris": ["https://example.com/webhook"],
+                },
+            },
+        ),
+        exception_if_vertex=(
+            "webhook_config parameter is not supported in Vertex AI"
+        ),
+    ),
 ]
 
 pytestmark = pytest_helper.setup(
@@ -757,4 +786,3 @@ async def test_generated_video_extension_from_source_poll_async(client):
   video2 = operation2.result.generated_videos[0].video
   assert video2.uri
   assert await client.aio.files.download(file=video2)
-

google/genai/types.py

@@ -11097,6 +11097,46 @@ class VideoGenerationMaskDict(TypedDict, total=False):
 VideoGenerationMaskOrDict = Union[VideoGenerationMask, VideoGenerationMaskDict]
 
 
+class WebhookConfig(_common.BaseModel):
+  """Configuration for webhook notifications.
+
+  Used to configure webhook endpoints that will receive notifications
+  when long-running operations (e.g., batch jobs, video generation) complete.
+  """
+
+  uris: Optional[list[str]] = Field(
+      default=None,
+      description="""The webhook URIs to receive notifications. If set, these
+      webhook URIs will be used instead of the registered webhooks.""",
+  )
+  user_metadata: Optional[dict[str, Any]] = Field(
+      default=None,
+      description="""User metadata that will be included in each webhook event
+      notification. Use this to attach custom key-value data to correlate
+      webhook events with your internal systems.""",
+  )
+
+
+class WebhookConfigDict(TypedDict, total=False):
+  """Configuration for webhook notifications.
+
+  Used to configure webhook endpoints that will receive notifications
+  when long-running operations (e.g., batch jobs, video generation) complete.
+  """
+
+  uris: Optional[list[str]]
+  """The webhook URIs to receive notifications. If set, these
+      webhook URIs will be used instead of the registered webhooks."""
+
+  user_metadata: Optional[dict[str, Any]]
+  """User metadata that will be included in each webhook event
+      notification. Use this to attach custom key-value data to correlate
+      webhook events with your internal systems."""
+
+
+WebhookConfigOrDict = Union[WebhookConfig, WebhookConfigDict]
+
+
 class GenerateVideosConfig(_common.BaseModel):
   """Configuration for generating videos."""
 
@@ -11180,6 +11220,11 @@ class GenerateVideosConfig(_common.BaseModel):
       default=None,
       description="""User specified labels to track billing usage.""",
   )
+  webhook_config: Optional[WebhookConfig] = Field(
+      default=None,
+      description="""Webhook configuration for receiving notifications when the
+      video generation operation completes.""",
+  )
 
 
 class GenerateVideosConfigDict(TypedDict, total=False):
@@ -11252,6 +11297,10 @@ class GenerateVideosConfigDict(TypedDict, total=False):
   labels: Optional[dict[str, str]]
   """User specified labels to track billing usage."""
 
+  webhook_config: Optional[WebhookConfigDict]
+  """Webhook configuration for receiving notifications when the
+      video generation operation completes."""
+
 
 GenerateVideosConfigOrDict = Union[
     GenerateVideosConfig, GenerateVideosConfigDict
@@ -16376,6 +16425,12 @@ class CreateBatchJobConfig(_common.BaseModel):
       "gs://path/to/output/data" or "bq://projectId.bqDatasetId.bqTableId".
       """,
   )
+  webhook_config: Optional[WebhookConfig] = Field(
+      default=None,
+      description="""Webhook configuration for receiving notifications when the batch
+      operation completes.
+      """,
+  )
 
 
 class CreateBatchJobConfigDict(TypedDict, total=False):
@@ -16393,6 +16448,11 @@ class CreateBatchJobConfigDict(TypedDict, total=False):
       "gs://path/to/output/data" or "bq://projectId.bqDatasetId.bqTableId".
       """
 
+  webhook_config: Optional[WebhookConfigDict]
+  """Webhook configuration for receiving notifications when the batch
+      operation completes.
+      """
+
 
 CreateBatchJobConfigOrDict = Union[
     CreateBatchJobConfig, CreateBatchJobConfigDict