Add reference_audios, generate_audio, and 1080p to video generation

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 ### Added
+- Added `reference_audios` and `generate_audio` parameters to video generation. `reference_audios` (on `client.video.generate` / `start` / `prepare`) is a list of audio sources for reference-to-video — each entry is a TypedDict such as `{"voice_id": "ara"}`; only supported for `grok-imagine-video-1.5`. `generate_audio` (on `generate` / `start` / `prepare`) controls whether the generated video includes audio (`true`) or is silent (`false`); when omitted the server defaults to `true`.
+- Added `"1080p"` as an accepted video `resolution` value (maps to `VIDEO_RESOLUTION_1080P`). Only supported on models that advertise 1080p (e.g. `grok-imagine-video-1.5` for image-to-video).
 - Added a `quality` parameter (`"low"`, `"medium"`) to image generation (`client.image.sample`, `sample_batch`, and batch `prepare`), mapping to the `GenerateImageRequest.quality` field. When omitted, the default is `"medium"`. Only supported for `grok-imagine-image-2.0`.
 - Added `grok-imagine-image-2.0` to the `ImageGenerationModel` known-model type literal
 - **`xhigh` Reasoning Effort**: Added `"xhigh"` as an accepted `reasoning_effort` value (maps to `EFFORT_XHIGH`; supported by models such as `grok-4.6`)
@@ -11,6 +13,9 @@
 - **Public File URLs**: Added `client.files.create_public_url()` and `client.files.revoke_public_url()` (sync and async) to create and revoke publicly shareable, unauthenticated URLs for stored files. `create_public_url()` accepts an optional `expires_after` (an `int` in seconds or a `datetime.timedelta`).
 - **Files List Filter**: `client.files.list()` (sync and async) now accepts an optional `filter` parameter to narrow results server-side by fields such as `content_type`, `size_bytes`, `created_at`, `upload_status`, and `public_url` (e.g. `filter='public_url != null'`).
 
+### Changed
+- Model type literals now match the current public model catalog: added `grok-imagine-video-1.5` and removed `grok-imagine-video-1.5-preview` (now an alias of `grok-imagine-video-1.5`) from `VideoGenerationModel`, and removed `grok-imagine-image-pro` (an alias of `grok-imagine-image-quality`) from `ImageGenerationModel`. These literals are type hints for editor autocomplete only — alias strings continue to work when passed to the API.
+
 ### Fixed
 - `chat.append(response)` now sets `tool_call_id` on replayed tool-role messages (recovered from the tool call echoed on the output), so servers can pair replayed tool turns with their originating calls. This fixes stateless multi-turn follow-ups to server-side tools whose results are re-hydrated by ID — e.g. editing a previously generated image in-memory without `previous_response_id`.
 

pyproject.toml

@@ -17,6 +17,7 @@ dependencies = [
   "aiohttp>=3.8.6,<4",
   "packaging>=25.0,<26",
   "opentelemetry-sdk>=1.36.0,<2",
+  "typing-extensions>=4.14.0,<5",
 ]
 requires-python = ">=3.10"
 classifiers = [

src/xai_sdk/aio/video.py

@@ -9,7 +9,7 @@
 from ..poll_timer import PollTimer
 from ..proto import batch_pb2, deferred_pb2, image_pb2, video_pb2
 from ..telemetry import get_tracer
-from ..types import VideoGenerationModel
+from ..types import ReferenceAudio, VideoGenerationModel
 from ..video import (
     DEFAULT_VIDEO_POLL_INTERVAL,
     DEFAULT_VIDEO_TIMEOUT,
@@ -47,6 +47,8 @@ def prepare(
         resolution: Optional[VideoResolution] = None,
         reference_image_urls: Optional[Sequence[str]] = None,
         reference_image_file_ids: Optional[Sequence[str]] = None,
+        reference_audios: Optional[Sequence[ReferenceAudio]] = None,
+        generate_audio: Optional[bool] = None,
         storage_options: Optional[Union[StorageOptions, image_pb2.StorageOptions]] = None,
     ) -> batch_pb2.BatchRequest:
         """Prepares a video generation request for batch processing.
@@ -81,6 +83,14 @@ def prepare(
                 reference-to-video (R2V) generation. May be combined with
                 ``reference_image_urls`` to mix URL/base64 and file-ID references
                 in the same request.
+            reference_audios: Optional list of reference audio sources for
+                reference-to-video (R2V) generation. Each entry is a TypedDict
+                such as ``{"voice_id": "ara"}``. See the
+                `voice catalog <https://docs.x.ai/developers/model-capabilities/audio/text-to-speech#voices>`_
+                for available presets. At most three entries. Only supported
+                for ``grok-imagine-video-1.5``.
+            generate_audio: Whether the generated video includes an audio track.
+                Defaults to ``True``. Set to ``False`` for a silent video.
             storage_options: Persist the result to the Files API. Accepts a dict
                 with a required ``filename`` and optional ``expires_after`` and ``public_url`` keys.
                 Set ``public_url`` to also create a publicly shareable URL.
@@ -133,6 +143,8 @@ def prepare(
             resolution=resolution,
             reference_image_urls=reference_image_urls,
             reference_image_file_ids=reference_image_file_ids,
+            reference_audios=reference_audios,
+            generate_audio=generate_audio,
             storage_options=storage_options,
         )
 
@@ -209,6 +221,8 @@ async def start(
         resolution: Optional[VideoResolution] = None,
         reference_image_urls: Optional[Sequence[str]] = None,
         reference_image_file_ids: Optional[Sequence[str]] = None,
+        reference_audios: Optional[Sequence[ReferenceAudio]] = None,
+        generate_audio: Optional[bool] = None,
         storage_options: Optional[Union[StorageOptions, image_pb2.StorageOptions]] = None,
     ) -> deferred_pb2.StartDeferredResponse:
         """Starts a video generation request and returns a request_id for polling.
@@ -227,6 +241,8 @@ async def start(
             resolution=resolution,
             reference_image_urls=reference_image_urls,
             reference_image_file_ids=reference_image_file_ids,
+            reference_audios=reference_audios,
+            generate_audio=generate_audio,
             storage_options=storage_options,
         )
 
@@ -256,6 +272,8 @@ async def generate(
         resolution: Optional[VideoResolution] = None,
         reference_image_urls: Optional[Sequence[str]] = None,
         reference_image_file_ids: Optional[Sequence[str]] = None,
+        reference_audios: Optional[Sequence[ReferenceAudio]] = None,
+        generate_audio: Optional[bool] = None,
         storage_options: Optional[Union[StorageOptions, image_pb2.StorageOptions]] = None,
         timeout: Optional[datetime.timedelta] = None,
         interval: Optional[datetime.timedelta] = None,
@@ -304,6 +322,14 @@ async def generate(
                 reference-to-video (R2V) generation. May be combined with
                 `reference_image_urls` to mix URL/base64 and file-ID references
                 in the same request.
+            reference_audios: Optional list of reference audio sources for
+                reference-to-video (R2V) generation. Each entry is a TypedDict
+                such as ``{"voice_id": "ara"}``. See the
+                `voice catalog <https://docs.x.ai/developers/model-capabilities/audio/text-to-speech#voices>`_
+                for available presets. At most three entries. Only supported
+                for ``grok-imagine-video-1.5``.
+            generate_audio: Whether the generated video includes an audio track.
+                Defaults to `True`. Set to `False` for a silent video.
             storage_options: Persist the result to the Files API. Accepts a dict
                 with a required ``filename`` and optional ``expires_after`` and ``public_url`` keys.
                 Set ``public_url`` to also create a publicly shareable URL.
@@ -384,6 +410,8 @@ async def generate(
             resolution=resolution,
             reference_image_urls=reference_image_urls,
             reference_image_file_ids=reference_image_file_ids,
+            reference_audios=reference_audios,
+            generate_audio=generate_audio,
             storage_options=storage_options,
         )
 

src/xai_sdk/proto/v5/video_pb2.pyi

@@ -25,6 +25,7 @@ class VideoResolution(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
     VIDEO_RESOLUTION_UNSPECIFIED: _ClassVar[VideoResolution]
     VIDEO_RESOLUTION_480P: _ClassVar[VideoResolution]
     VIDEO_RESOLUTION_720P: _ClassVar[VideoResolution]
+    VIDEO_RESOLUTION_1080P: _ClassVar[VideoResolution]
 VIDEO_ASPECT_RATIO_UNSPECIFIED: VideoAspectRatio
 VIDEO_ASPECT_RATIO_1_1: VideoAspectRatio
 VIDEO_ASPECT_RATIO_16_9: VideoAspectRatio
@@ -36,6 +37,7 @@ VIDEO_ASPECT_RATIO_2_3: VideoAspectRatio
 VIDEO_RESOLUTION_UNSPECIFIED: VideoResolution
 VIDEO_RESOLUTION_480P: VideoResolution
 VIDEO_RESOLUTION_720P: VideoResolution
+VIDEO_RESOLUTION_1080P: VideoResolution
 
 class VideoUrlContent(_message.Message):
     __slots__ = ("url", "file_id")