feat(v2): mark the 2.0 audio API as preview

client.audio now mounts lazily and emits a one-time FutureWarning on
first access; Audio/AsyncAudio docstrings and the examples READMEs
carry the same preview note.

Author: zhansheng.lzs

dashscope/v2/client.py

@@ -10,6 +10,7 @@
 
 from pathlib import Path
 from typing import Any, Dict, Mapping, Optional, Union
+import warnings
 
 import httpx
 
@@ -116,14 +117,33 @@ def __init__(
         self.models = Models(self)
         self.images = Images(self)
         self.videos = Videos(self)
-        self.audio = Audio(self)
+        self._audio = None
         self.fine_tunes = FineTunes(self)
         self.deployments = Deployments(self)
         self.rl = Rl(self)
         self.apps = Apps(self)
         self.tingwu = TingWu(self)
         self._agentstudio = None
 
+    @property
+    def audio(self) -> "Audio":
+        """Audio capabilities (lazily mounted).
+
+        Preview: the 2.0 audio API surface is not final and may change
+        in a future release.
+        """
+        if self._audio is None:
+            warnings.warn(
+                "dashscope 2.0 audio API is a preview and may change "
+                "in a future release.",
+                FutureWarning,
+                stacklevel=2,
+            )
+            self._audio = Audio(self)
+        audio = self._audio
+        assert audio is not None
+        return audio
+
     @property
     def reinforcement_learning(self) -> "Rl":
         """Long-form alias for ``client.rl``."""
@@ -338,14 +358,33 @@ def __init__(
         self.models = AsyncModels(self)
         self.images = AsyncImages(self)
         self.videos = AsyncVideos(self)
-        self.audio = AsyncAudio(self)
+        self._audio = None
         self.fine_tunes = AsyncFineTunes(self)
         self.deployments = AsyncDeployments(self)
         self.rl = AsyncRl(self)
         self.apps = AsyncApps(self)
         self.tingwu = AsyncTingWu(self)
         self._agentstudio = None
 
+    @property
+    def audio(self) -> "AsyncAudio":
+        """Audio capabilities (lazily mounted).
+
+        Preview: the 2.0 audio API surface is not final and may change
+        in a future release.
+        """
+        if self._audio is None:
+            warnings.warn(
+                "dashscope 2.0 audio API is a preview and may change "
+                "in a future release.",
+                FutureWarning,
+                stacklevel=2,
+            )
+            self._audio = AsyncAudio(self)
+        audio = self._audio
+        assert audio is not None
+        return audio
+
     @property
     def reinforcement_learning(self) -> "AsyncRl":
         """Long-form alias for ``client.rl``."""

dashscope/v2/resources/audio/__init__.py

@@ -78,6 +78,12 @@
 
 
 class Audio:
+    """Sync audio surface.
+
+    Preview: the 2.0 audio API surface is not final and may change in
+    a future release.
+    """
+
     def __init__(self, client) -> None:
         self.asr = Asr(client)
         self.tts = Tts(client)
@@ -95,6 +101,9 @@ class AsyncAudio:
     Only batch transcription is exposed here; the ws realtime resources
     (``asr.recognize``, ``tts``, ``realtime``) are sync-only by design
     (design doc M3 3.5).
+
+    Preview: the 2.0 audio API surface is not final and may change in
+    a future release.
     """
 
     def __init__(self, client) -> None:

examples/README.md

@@ -93,8 +93,8 @@ Uniform style: `client = dashscope.Client()` (reads the key from the `DASHSCOPE_
 | `text_generation/chat.py` | Text generation: one-line `dashscope.chat()`, non-streaming, streaming (text_stream) |
 | `text_generation/tokenization.py` | Token counting |
 | `multimodal_vision/multimodal_chat.py` | Multimodal chat (qwen-vl image understanding) |
-| `audio_speech/audio_tts.py` | Speech synthesis (one-shot + streaming) |
-| `audio_speech/audio_asr.py` | Batch speech recognition |
+| `audio_speech/audio_tts.py` | Speech synthesis (one-shot + streaming); 2.0 audio API is a preview and may change |
+| `audio_speech/audio_asr.py` | Batch speech recognition; 2.0 audio API is a preview and may change |
 | `audio_speech/tingwu.py` | TingWu offline tasks and realtime sessions |
 | `image_video_synthesis/images.py` | Image generation: one-call generate-and-wait + the manual jobs flow |
 | `image_video_synthesis/videos.py` | Video generation: one-call generate-and-wait + the manual jobs flow |

examples/README_zh.md

@@ -93,8 +93,8 @@ examples/
 | `text_generation/chat.py` | 文本生成：一行 `dashscope.chat()`、非流式、流式（text_stream） |
 | `text_generation/tokenization.py` | token 计数 |
 | `multimodal_vision/multimodal_chat.py` | 多模态对话（qwen-vl 图像理解） |
-| `audio_speech/audio_tts.py` | 语音合成（一次性 + 流式） |
-| `audio_speech/audio_asr.py` | 批量语音识别 |
+| `audio_speech/audio_tts.py` | 语音合成（一次性 + 流式）；2.0 audio API 为预览，后续可能变更 |
+| `audio_speech/audio_asr.py` | 批量语音识别；2.0 audio API 为预览，后续可能变更 |
 | `audio_speech/tingwu.py` | 听悟离线任务与实时会话 |
 | `image_video_synthesis/images.py` | 图像生成：一键生成并等待 + 手动 jobs 流程 |
 | `image_video_synthesis/videos.py` | 视频生成：一键生成并等待 + 手动 jobs 流程 |