feat: Deprecate legacy response_format and publish new polymorphic field.

PiperOrigin-RevId: 908361634

Author: google-genai-bot

google/genai/_interactions/resources/interactions.py

@@ -75,7 +75,7 @@ def create(
         background: bool | Omit = omit,
         generation_config: GenerationConfigParam | Omit = omit,
         previous_interaction_id: str | Omit = omit,
-        response_format: object | Omit = omit,
+        response_format: interaction_create_params.ResponseFormat | Omit = omit,
         response_mime_type: str | Omit = omit,
         response_modalities: List[Literal["text", "image", "audio", "video", "document"]] | Omit = omit,
         service_tier: Literal["flex", "standard", "priority"] | Omit = omit,
@@ -146,7 +146,7 @@ def create(
         background: bool | Omit = omit,
         generation_config: GenerationConfigParam | Omit = omit,
         previous_interaction_id: str | Omit = omit,
-        response_format: object | Omit = omit,
+        response_format: interaction_create_params.ResponseFormat | Omit = omit,
         response_mime_type: str | Omit = omit,
         response_modalities: List[Literal["text", "image", "audio", "video", "document"]] | Omit = omit,
         service_tier: Literal["flex", "standard", "priority"] | Omit = omit,
@@ -222,7 +222,7 @@ def create(
         agent_config: interaction_create_params.AgentConfig | Omit = omit,
         background: bool | Omit = omit,
         previous_interaction_id: str | Omit = omit,
-        response_format: object | Omit = omit,
+        response_format: interaction_create_params.ResponseFormat | Omit = omit,
         response_mime_type: str | Omit = omit,
         response_modalities: List[Literal["text", "image", "audio", "video", "document"]] | Omit = omit,
         service_tier: Literal["flex", "standard", "priority"] | Omit = omit,
@@ -300,7 +300,7 @@ def create(
         agent_config: interaction_create_params.AgentConfig | Omit = omit,
         background: bool | Omit = omit,
         previous_interaction_id: str | Omit = omit,
-        response_format: object | Omit = omit,
+        response_format: interaction_create_params.ResponseFormat | Omit = omit,
         response_mime_type: str | Omit = omit,
         response_modalities: List[Literal["text", "image", "audio", "video", "document"]] | Omit = omit,
         service_tier: Literal["flex", "standard", "priority"] | Omit = omit,
@@ -370,7 +370,7 @@ def create(
         background: bool | Omit = omit,
         generation_config: GenerationConfigParam | Omit = omit,
         previous_interaction_id: str | Omit = omit,
-        response_format: object | Omit = omit,
+        response_format: interaction_create_params.ResponseFormat | Omit = omit,
         response_mime_type: str | Omit = omit,
         response_modalities: List[Literal["text", "image", "audio", "video", "document"]] | Omit = omit,
         service_tier: Literal["flex", "standard", "priority"] | Omit = omit,
@@ -439,7 +439,7 @@ def create(
         background: bool | Omit = omit,
         generation_config: GenerationConfigParam | Omit = omit,
         previous_interaction_id: str | Omit = omit,
-        response_format: object | Omit = omit,
+        response_format: interaction_create_params.ResponseFormat | Omit = omit,
         response_mime_type: str | Omit = omit,
         response_modalities: List[Literal["text", "image", "audio", "video", "document"]] | Omit = omit,
         service_tier: Literal["flex", "standard", "priority"] | Omit = omit,
@@ -771,7 +771,7 @@ async def create(
         background: bool | Omit = omit,
         generation_config: GenerationConfigParam | Omit = omit,
         previous_interaction_id: str | Omit = omit,
-        response_format: object | Omit = omit,
+        response_format: interaction_create_params.ResponseFormat | Omit = omit,
         response_mime_type: str | Omit = omit,
         response_modalities: List[Literal["text", "image", "audio", "video", "document"]] | Omit = omit,
         service_tier: Literal["flex", "standard", "priority"] | Omit = omit,
@@ -842,7 +842,7 @@ async def create(
         background: bool | Omit = omit,
         generation_config: GenerationConfigParam | Omit = omit,
         previous_interaction_id: str | Omit = omit,
-        response_format: object | Omit = omit,
+        response_format: interaction_create_params.ResponseFormat | Omit = omit,
         response_mime_type: str | Omit = omit,
         response_modalities: List[Literal["text", "image", "audio", "video", "document"]] | Omit = omit,
         service_tier: Literal["flex", "standard", "priority"] | Omit = omit,
@@ -918,7 +918,7 @@ async def create(
         agent_config: interaction_create_params.AgentConfig | Omit = omit,
         background: bool | Omit = omit,
         previous_interaction_id: str | Omit = omit,
-        response_format: object | Omit = omit,
+        response_format: interaction_create_params.ResponseFormat | Omit = omit,
         response_mime_type: str | Omit = omit,
         response_modalities: List[Literal["text", "image", "audio", "video", "document"]] | Omit = omit,
         service_tier: Literal["flex", "standard", "priority"] | Omit = omit,
@@ -996,7 +996,7 @@ async def create(
         agent_config: interaction_create_params.AgentConfig | Omit = omit,
         background: bool | Omit = omit,
         previous_interaction_id: str | Omit = omit,
-        response_format: object | Omit = omit,
+        response_format: interaction_create_params.ResponseFormat | Omit = omit,
         response_mime_type: str | Omit = omit,
         response_modalities: List[Literal["text", "image", "audio", "video", "document"]] | Omit = omit,
         service_tier: Literal["flex", "standard", "priority"] | Omit = omit,
@@ -1066,7 +1066,7 @@ async def create(
         background: bool | Omit = omit,
         generation_config: GenerationConfigParam | Omit = omit,
         previous_interaction_id: str | Omit = omit,
-        response_format: object | Omit = omit,
+        response_format: interaction_create_params.ResponseFormat | Omit = omit,
         response_mime_type: str | Omit = omit,
         response_modalities: List[Literal["text", "image", "audio", "video", "document"]] | Omit = omit,
         service_tier: Literal["flex", "standard", "priority"] | Omit = omit,
@@ -1135,7 +1135,7 @@ async def create(
         background: bool | Omit = omit,
         generation_config: GenerationConfigParam | Omit = omit,
         previous_interaction_id: str | Omit = omit,
-        response_format: object | Omit = omit,
+        response_format: interaction_create_params.ResponseFormat | Omit = omit,
         response_mime_type: str | Omit = omit,
         response_modalities: List[Literal["text", "image", "audio", "video", "document"]] | Omit = omit,
         service_tier: Literal["flex", "standard", "priority"] | Omit = omit,

google/genai/_interactions/types/__init__.py

@@ -79,12 +79,16 @@
 from .function_result_step import FunctionResultStep as FunctionResultStep
 from .google_search_result import GoogleSearchResult as GoogleSearchResult
 from .place_citation_param import PlaceCitationParam as PlaceCitationParam
+from .text_response_format import TextResponseFormat as TextResponseFormat
 from .webhook_config_param import WebhookConfigParam as WebhookConfigParam
+from .audio_response_format import AudioResponseFormat as AudioResponseFormat
 from .file_search_call_step import FileSearchCallStep as FileSearchCallStep
 from .google_maps_call_step import GoogleMapsCallStep as GoogleMapsCallStep
+from .image_response_format import ImageResponseFormat as ImageResponseFormat
 from .interaction_sse_event import InteractionSSEEvent as InteractionSSEEvent
 from .url_context_call_step import URLContextCallStep as URLContextCallStep
 from .user_input_step_param import UserInputStepParam as UserInputStepParam
+from .video_response_format import VideoResponseFormat as VideoResponseFormat
 from .webhook_create_params import WebhookCreateParams as WebhookCreateParams
 from .webhook_list_response import WebhookListResponse as WebhookListResponse
 from .webhook_ping_response import WebhookPingResponse as WebhookPingResponse
@@ -112,11 +116,15 @@
 from .function_result_step_param import FunctionResultStepParam as FunctionResultStepParam
 from .google_maps_call_arguments import GoogleMapsCallArguments as GoogleMapsCallArguments
 from .interaction_complete_event import InteractionCompleteEvent as InteractionCompleteEvent
+from .text_response_format_param import TextResponseFormatParam as TextResponseFormatParam
 from .url_context_call_arguments import URLContextCallArguments as URLContextCallArguments
+from .audio_response_format_param import AudioResponseFormatParam as AudioResponseFormatParam
 from .file_search_call_step_param import FileSearchCallStepParam as FileSearchCallStepParam
 from .google_maps_call_step_param import GoogleMapsCallStepParam as GoogleMapsCallStepParam
+from .image_response_format_param import ImageResponseFormatParam as ImageResponseFormatParam
 from .mcp_server_tool_result_step import MCPServerToolResultStep as MCPServerToolResultStep
 from .url_context_call_step_param import URLContextCallStepParam as URLContextCallStepParam
+from .video_response_format_param import VideoResponseFormatParam as VideoResponseFormatParam
 from .google_search_call_arguments import GoogleSearchCallArguments as GoogleSearchCallArguments
 from .code_execution_call_arguments import CodeExecutionCallArguments as CodeExecutionCallArguments
 from .file_search_result_step_param import FileSearchResultStepParam as FileSearchResultStepParam

google/genai/_interactions/types/audio_response_format.py

@@ -0,0 +1,48 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from typing_extensions import Literal
+
+from pydantic import Field as FieldInfo
+
+from .._models import BaseModel
+
+__all__ = ["AudioResponseFormat"]
+
+
+class AudioResponseFormat(BaseModel):
+    """Configuration for audio output format."""
+
+    type: Literal["audio"]
+
+    bit_rate: Optional[int] = FieldInfo(alias="bitRate", default=None)
+    """Bit rate in bits per second (bps).
+
+    Only applicable for compressed formats (MP3, Opus).
+    """
+
+    delivery: Optional[Literal["inline", "url"]] = None
+    """The delivery mode for the audio output."""
+
+    mime_type: Optional[
+        Literal["audio/mp3", "audio/ogg_opus", "audio/l16", "audio/wav", "audio/alaw", "audio/mulaw"]
+    ] = FieldInfo(alias="mimeType", default=None)
+    """The MIME type of the audio output."""
+
+    sample_rate: Optional[int] = FieldInfo(alias="sampleRate", default=None)
+    """Sample rate in Hz."""

google/genai/_interactions/types/audio_response_format_param.py

@@ -0,0 +1,48 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, Required, Annotated, TypedDict
+
+from .._utils import PropertyInfo
+
+__all__ = ["AudioResponseFormatParam"]
+
+
+class AudioResponseFormatParam(TypedDict, total=False):
+    """Configuration for audio output format."""
+
+    type: Required[Literal["audio"]]
+
+    bit_rate: Annotated[int, PropertyInfo(alias="bitRate")]
+    """Bit rate in bits per second (bps).
+
+    Only applicable for compressed formats (MP3, Opus).
+    """
+
+    delivery: Literal["inline", "url"]
+    """The delivery mode for the audio output."""
+
+    mime_type: Annotated[
+        Literal["audio/mp3", "audio/ogg_opus", "audio/l16", "audio/wav", "audio/alaw", "audio/mulaw"],
+        PropertyInfo(alias="mimeType"),
+    ]
+    """The MIME type of the audio output."""
+
+    sample_rate: Annotated[int, PropertyInfo(alias="sampleRate")]
+    """Sample rate in Hz."""

google/genai/_interactions/types/image_response_format.py

@@ -0,0 +1,45 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from typing_extensions import Literal
+
+from pydantic import Field as FieldInfo
+
+from .._models import BaseModel
+
+__all__ = ["ImageResponseFormat"]
+
+
+class ImageResponseFormat(BaseModel):
+    """Configuration for image output format."""
+
+    type: Literal["image"]
+
+    aspect_ratio: Optional[
+        Literal["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "1:8", "8:1", "1:4", "4:1"]
+    ] = FieldInfo(alias="aspectRatio", default=None)
+    """The aspect ratio for the image output."""
+
+    delivery: Optional[Literal["inline", "url"]] = None
+    """The delivery mode for the image output."""
+
+    image_size: Optional[Literal["512", "1K", "2K", "4K"]] = FieldInfo(alias="imageSize", default=None)
+    """The size of the image output."""
+
+    mime_type: Optional[Literal["image/jpeg"]] = FieldInfo(alias="mimeType", default=None)
+    """The MIME type of the image output."""

google/genai/_interactions/types/image_response_format_param.py

@@ -0,0 +1,45 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, Required, Annotated, TypedDict
+
+from .._utils import PropertyInfo
+
+__all__ = ["ImageResponseFormatParam"]
+
+
+class ImageResponseFormatParam(TypedDict, total=False):
+    """Configuration for image output format."""
+
+    type: Required[Literal["image"]]
+
+    aspect_ratio: Annotated[
+        Literal["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "1:8", "8:1", "1:4", "4:1"],
+        PropertyInfo(alias="aspectRatio"),
+    ]
+    """The aspect ratio for the image output."""
+
+    delivery: Literal["inline", "url"]
+    """The delivery mode for the image output."""
+
+    image_size: Annotated[Literal["512", "1K", "2K", "4K"], PropertyInfo(alias="imageSize")]
+    """The size of the image output."""
+
+    mime_type: Annotated[Literal["image/jpeg"], PropertyInfo(alias="mimeType")]
+    """The MIME type of the image output."""

google/genai/_interactions/types/interaction.py

@@ -33,9 +33,13 @@
 from .webhook_config import WebhookConfig
 from .document_content import DocumentContent
 from .dynamic_agent_config import DynamicAgentConfig
+from .text_response_format import TextResponseFormat
+from .audio_response_format import AudioResponseFormat
+from .image_response_format import ImageResponseFormat
+from .video_response_format import VideoResponseFormat
 from .deep_research_agent_config import DeepResearchAgentConfig
 
-__all__ = ["Interaction", "AgentConfig", "Input"]
+__all__ = ["Interaction", "AgentConfig", "Input", "ResponseFormat", "ResponseFormatResponseFormatList"]
 
 AgentConfig: TypeAlias = Annotated[
     Union[DynamicAgentConfig, DeepResearchAgentConfig], PropertyInfo(discriminator="type")
@@ -45,6 +49,19 @@
     str, List[Step], List[Content], TextContent, ImageContent, AudioContent, DocumentContent, VideoContent
 ]
 
+ResponseFormatResponseFormatList: TypeAlias = Union[
+    AudioResponseFormat, TextResponseFormat, ImageResponseFormat, VideoResponseFormat, object
+]
+
+ResponseFormat: TypeAlias = Union[
+    List[ResponseFormatResponseFormatList],
+    AudioResponseFormat,
+    TextResponseFormat,
+    ImageResponseFormat,
+    VideoResponseFormat,
+    object,
+]
+
 
 class Interaction(BaseModel):
     """The Interaction resource."""
@@ -90,7 +107,7 @@ class Interaction(BaseModel):
     previous_interaction_id: Optional[str] = None
     """The ID of the previous interaction, if any."""
 
-    response_format: Optional[object] = None
+    response_format: Optional[ResponseFormat] = None
     """
     Enforces that the generated response is a JSON object that complies with the
     JSON schema specified in this field.