Make ai.generate private

docs/ai-python/content/docs/basics/streaming.mdx

@@ -136,15 +136,3 @@ async with ai.stream(model, messages) as stream:
 for f in stream.message.files:
     print(f.media_type)
 ```
-
-Use `ai.generate` for dedicated image and video models:
-
-```python
-result = await ai.generate(
-    model,
-    [ai.user_message("A watercolor mothership over a quiet city.")],
-    ai.ImageParams(n=1, aspect_ratio="16:9"),
-)
-
-image = result.images[0]
-```

docs/ai-python/content/docs/reference/ai/index.mdx

@@ -21,8 +21,6 @@ These top-level exports have their own pages under `ai`.
 
 - [`stream`](/docs/reference/ai/stream): Call a model and iterate response
   events. The same page documents `Stream`.
-- [`generate`](/docs/reference/ai/generate): Call non-streaming media
-  generation models.
 - [`get_model`](/docs/reference/ai/get-model): Resolve a model id into a
   `Model`.
 - [`get_provider`](/docs/reference/ai/get-provider): Resolve and configure a
@@ -124,8 +122,7 @@ await protocol.generate(client, model, messages, params, provider=provider.name)
 
 Model params are top-level `ai` types.
 
-Use `InferenceRequestParams` with `stream` and `Agent.run`. Use `ImageParams`
-and `VideoParams` with `generate`.
+Use `InferenceRequestParams` with `stream` and `Agent.run`.
 
 ```python
 params = ai.InferenceRequestParams().with_temperature(0)
@@ -176,28 +173,6 @@ Routing params:
 - `ProviderRankingStrategy`
 - `GLOBAL`
 
-Media generation params:
-
-```python
-ai.ImageParams(
-    n=1,
-    size=None,
-    aspect_ratio=None,
-    seed=None,
-    provider_options={},
-)
-
-ai.VideoParams(
-    n=1,
-    aspect_ratio=None,
-    resolution=None,
-    duration=None,
-    fps=None,
-    seed=None,
-    provider_options={},
-)
-```
-
 ## Messages
 
 Message builders create `Message` values.

docs/ai-python/content/docs/reference/ai/meta.json

@@ -3,7 +3,6 @@
   "description": "Reference for top-level ai exports.",
   "pages": [
     "stream",
-    "generate",
     "get-model",
     "get-provider",
     "tool-decorator",

examples/.test_scripts/run-examples.py

@@ -13,7 +13,7 @@
     uv run examples/.test_scripts/run-examples.py --model MODEL
         # patch ai.get_model() to use the given model for every sample
     uv run examples/.test_scripts/run-examples.py --protocol=responses
-        # patch model/provider helpers and ai.stream()/ai.generate()
+        # patch model/provider helpers, ai.stream(), and experimental_generate()
 """
 
 import argparse

examples/.test_scripts/run-with-patched-model.py

@@ -86,7 +86,7 @@ def main() -> None:
 
     original_get_model = _model.get_model
     original_stream = _api.stream
-    original_generate = _api.generate
+    original_generate = _api.experimental_generate
 
     def selected_protocol() -> ai.ProviderProtocol[Any] | None:
         if protocol_factory is None:
@@ -203,10 +203,7 @@ def __init__(
         cast("Any", core).stream = patched_stream
         cast("Any", _api).stream = patched_stream
 
-        cast("Any", ai).generate = patched_generate
-        cast("Any", models).generate = patched_generate
-        cast("Any", core).generate = patched_generate
-        cast("Any", _api).generate = patched_generate
+        cast("Any", _api).experimental_generate = patched_generate
 
     sys.argv = [args.file]
     runpy.run_path(args.file, run_name="__main__")

examples/media/image_edit.py

@@ -10,6 +10,7 @@
 import pathlib
 
 import ai
+from ai.models.core import api, params
 
 model = ai.get_model("openai/gpt-image-1")
 
@@ -32,8 +33,8 @@ async def main() -> None:
         ),
     ]
 
-    result = await ai.generate(
-        model, messages, ai.ImageParams(size="1024x1024")
+    result = await api.experimental_generate(
+        model, messages, params.ImageParams(size="1024x1024")
     )
 
     print(f"Generated {len(result.images)} edited image(s)")

examples/media/image_generation.py

@@ -1,10 +1,11 @@
-"""Image generation — dedicated image model via generate()."""
+"""Image generation — dedicated image model via experimental_generate()."""
 
 import asyncio
 import base64
 import pathlib
 
 import ai
+from ai.models.core import api, params
 
 model = ai.get_model("google/imagen-4.0-generate-001")
 
@@ -18,8 +19,8 @@
 
 
 async def main() -> None:
-    result = await ai.generate(
-        model, messages, ai.ImageParams(n=2, aspect_ratio="16:9")
+    result = await api.experimental_generate(
+        model, messages, params.ImageParams(n=2, aspect_ratio="16:9")
     )
 
     print(f"Generated {len(result.images)} image(s)")

examples/media/video_generation.py

@@ -1,10 +1,11 @@
-"""Video generation — dedicated video model via generate()."""
+"""Video generation — dedicated video model via experimental_generate()."""
 
 import asyncio
 import base64
 import pathlib
 
 import ai
+from ai.models.core import api, params
 
 model = ai.get_model("google/veo-3.0-generate-001")
 
@@ -19,10 +20,10 @@
 async def main() -> None:
     print("Generating video (this may take a minute or two)...")
 
-    result = await ai.generate(
+    result = await api.experimental_generate(
         model,
         messages,
-        ai.VideoParams(aspect_ratio="16:9", duration=8),
+        params.VideoParams(aspect_ratio="16:9", duration=8),
     )
 
     print(f"Generated {len(result.videos)} video(s)")

src/ai/__init__.py

@@ -58,7 +58,6 @@
     CloudRegion,
     ContextManagementParams,
     GeoRegion,
-    ImageParams,
     InferenceRequestParams,
     MinPSamplerParams,
     Model,
@@ -85,8 +84,6 @@
     TopKSamplerParams,
     TopPSamplerParams,
     Unset,
-    VideoParams,
-    generate,
     get_model,
     probe,
     stream,
@@ -123,7 +120,6 @@
     "HTTPErrorContext",
     "HookDeferredException",
     "HookRegistry",
-    "ImageParams",
     "InferenceRequestParams",
     "InstallationError",
     "MinPSamplerParams",
@@ -178,7 +174,6 @@
     "TopPSamplerParams",
     "Unset",
     "UnsupportedProviderError",
-    "VideoParams",
     "assistant_message",
     "cancel_hook",
     "content_output",
@@ -187,7 +182,6 @@
     "errors",
     "events",
     "file_part",
-    "generate",
     "get_hook_registry",
     "get_model",
     "get_provider",

src/ai/models/__init__.py

@@ -35,7 +35,6 @@
 from ..providers.base import Provider, ProviderProtocol
 from .core.api import (
     Stream,
-    generate,
     probe,
     stream,
 )
@@ -48,9 +47,7 @@
     CacheParams,
     CloudRegion,
     ContextManagementParams,
-    GenerateParams,
     GeoRegion,
-    ImageParams,
     InferenceRequestParams,
     MinPSamplerParams,
     ModelProviderDefault,
@@ -73,7 +70,6 @@
     TopKSamplerParams,
     TopPSamplerParams,
     Unset,
-    VideoParams,
 )
 
 __all__ = [
@@ -84,9 +80,7 @@
     "CacheParams",
     "CloudRegion",
     "ContextManagementParams",
-    "GenerateParams",
     "GeoRegion",
-    "ImageParams",
     "InferenceRequestParams",
     "MinPSamplerParams",
     "Model",
@@ -113,8 +107,6 @@
     "TopKSamplerParams",
     "TopPSamplerParams",
     "Unset",
-    "VideoParams",
-    "generate",
     "get_model",
     "probe",
     "stream",

src/ai/models/core/__init__.py

@@ -4,7 +4,6 @@
 from . import helpers
 from .api import (
     Stream,
-    generate,
     probe,
     stream,
 )
@@ -17,9 +16,7 @@
     CacheParams,
     CloudRegion,
     ContextManagementParams,
-    GenerateParams,
     GeoRegion,
-    ImageParams,
     InferenceRequestParams,
     MinPSamplerParams,
     ModelProviderDefault,
@@ -42,7 +39,6 @@
     TopKSamplerParams,
     TopPSamplerParams,
     Unset,
-    VideoParams,
 )
 
 __all__ = [
@@ -53,9 +49,7 @@
     "CacheParams",
     "CloudRegion",
     "ContextManagementParams",
-    "GenerateParams",
     "GeoRegion",
-    "ImageParams",
     "InferenceRequestParams",
     "MinPSamplerParams",
     "Model",
@@ -81,8 +75,6 @@
     "TopKSamplerParams",
     "TopPSamplerParams",
     "Unset",
-    "VideoParams",
-    "generate",
     "get_model",
     "helpers",
     "probe",

src/ai/models/core/api.py

@@ -606,12 +606,15 @@ async def _stream(
             await s.aclose()
 
 
-async def generate(
+async def experimental_generate(
     model: model_.Model,
     messages: list[types.messages.Message],
     params: params_.GenerateParams,
 ) -> types.messages.Message:
-    """Generate a non-streaming response (images, video, etc.)."""
+    """Generate a non-streaming response (images, video, etc.).
+
+    Experimental: not part of the stable API, may change or be removed.
+    """
     request = _GenerateRequest(model, list(messages), params)
     async with telemetry.span(
         telemetry.AiGenerateSpanData(

src/ai/providers/ai_gateway/protocol.py

@@ -1060,7 +1060,7 @@ async def _generate_image(
     gateway: gateway_client.GatewayClient,
     model: core.model.Model,
     messages: list[types.messages.Message],
-    params: core.ImageParams,
+    params: params_.ImageParams,
 ) -> types.messages.Message:
     """Hit ``/image-model`` and return a Message with FileParts."""
     prompt = _extract_prompt(messages)
@@ -1101,7 +1101,7 @@ async def _generate_video(
     gateway: gateway_client.GatewayClient,
     model: core.model.Model,
     messages: list[types.messages.Message],
-    params: core.VideoParams,
+    params: params_.VideoParams,
 ) -> types.messages.Message:
     """Hit ``/video-model`` (SSE) and return a Message with FileParts."""
     prompt = _extract_prompt(messages)
@@ -1168,11 +1168,11 @@ async def generate(
     gateway: gateway_client.GatewayClient,
     model: core.model.Model,
     messages: list[types.messages.Message],
-    params: core.GenerateParams,
+    params: params_.GenerateParams,
 ) -> types.messages.Message:
     """Generate media through the AI Gateway."""
     try:
-        if isinstance(params, core.VideoParams):
+        if isinstance(params, params_.VideoParams):
             return await _generate_video(gateway, model, messages, params)
         return await _generate_image(gateway, model, messages, params)
     except client_errors.GatewayError as exc:
@@ -1210,7 +1210,7 @@ async def generate(
         client: gateway_client.GatewayClient,
         model: core.model.Model,
         messages: list[types.messages.Message],
-        params: core.GenerateParams,
+        params: params_.GenerateParams,
         *,
         provider: str,
     ) -> types.messages.Message: