yunmao 0.1.0__tar.gz

yunmao-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+**/.venv/
+**/.pytest_cache/
+**/__pycache__/
+**/*.pyc
+**/node_modules/
+**/dist/
+**/build/
+**/*.egg-info/
+**/.coverage

yunmao-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: yunmao
+Version: 0.1.0
+Summary: Official Python SDK for Yunmao Open Platform APIs
+Project-URL: Homepage, https://open.xjymai.com
+Project-URL: Documentation, https://open.xjymai.com/docs
+Author: Yunmao
+License: MIT
+Keywords: asr,openapi,translation,tts,yunmao
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.26
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Yunmao Python SDK
+
+Python SDK for Yunmao Open Platform.
+
+## Install
+
+```bash
+pip install yunmao
+```
+
+For local development:
+
+```bash
+pip install -e ".[test]"
+```
+
+## Quick Start
+
+```python
+from yunmao import YunmaoClient
+
+client = YunmaoClient(
+    api_key="ym_sk_xxxxxxxxxxxxxxxxx",
+    # Use this for dev testing:
+    # base_url="https://gateway-dpkhzbkdjj.cn-hangzhou.fcapp.run",
+)
+
+result = client.translate.text(
+    "Welcome to Yunmao Open Platform.",
+    target_language="ug",
+    source_language="auto",
+)
+print(result["translated_text"])
+```
+
+The default `base_url` is `https://api.xjymai.com`. Do not use production API keys for development tests; pass the dev gateway `base_url` with a dev API key.
+
+## Examples
+
+```python
+client.translate.text("hello", target_language="ug")
+```
+
+```python
+client.tts.synthesize(
+    "欢迎使用云猫开放平台。",
+    voice_id="voice_id_here",
+    language_code="zh",
+    speed=1.0,
+)
+```
+
+```python
+client.asr.recognize(
+    "/path/to/audio.wav",
+    language_hint="mul_cn",
+    sample_rate=16000,
+)
+```
+
+```python
+client.video.parse(url="https://v.douyin.com/example/")
+```
+
+```python
+client.oil.price(province="新疆")
+```
+
+```python
+client.voices.clone(
+    name="Demo voice",
+    language_code="zh",
+    ref_text="这是样本音频中的朗读文本。",
+    sample_url="https://oss.example.com/sample.wav",
+)
+```
+
+## Errors
+
+```python
+from yunmao import YunmaoAPIError
+
+try:
+    client.translate.text("hello", target_language="ug")
+except YunmaoAPIError as error:
+    print(error.status_code)
+    print(error.code)
+    print(error.message)
+    print(error.request_id)
+```
+
+The SDK preserves:
+
+- `status_code`: HTTP status
+- `code`: Yunmao business error code
+- `message`: server `msg`
+- `request_id`: from `X-Request-ID`, `request_id`, or `requestId` when the server provides it
+- `response_body`: parsed raw response body
+
+Common Open API codes:
+
+| code | HTTP | Meaning |
+| --- | --- | --- |
+| `40102` | 401 | Invalid or missing API Key |
+| `40301` | 403 | API Key scope denied |
+| `40302` | 403 | Quota exhausted |
+| `40303` | 403 | Real-name verification required |
+| `40401` | 404 | Resource not found |
+| `42201` | 422 | Invalid JSON body |
+| `42202` | 422 | Invalid parameter |
+| `42901` | 429 | Concurrency exceeded |
+| `50201` | 502 | Downstream service unavailable |
+| `50301` | 503 | Database unavailable |
+| `50000` | 500 | Internal server error |
+
+## Voice List Note
+
+The current voice list endpoint is a console JWT endpoint (`GET /api/v1/open-platform/voices`), not an API Key Open API endpoint. This SDK exposes API Key calls only, so it includes `voices.clone()` but does not expose voice listing yet. Add a server-side `GET /v1/voices` endpoint before adding that SDK method.
+
+## Test
+
+```bash
+pytest
+```
+
+Tests use `httpx.MockTransport`; they do not call dev or production paid APIs.
+
+## Publish
+
+```bash
+python -m pip install build twine
+python -m build
+twine upload dist/*
+```

yunmao-0.1.0/README.md

@@ -0,0 +1,134 @@
+# Yunmao Python SDK
+
+Python SDK for Yunmao Open Platform.
+
+## Install
+
+```bash
+pip install yunmao
+```
+
+For local development:
+
+```bash
+pip install -e ".[test]"
+```
+
+## Quick Start
+
+```python
+from yunmao import YunmaoClient
+
+client = YunmaoClient(
+    api_key="ym_sk_xxxxxxxxxxxxxxxxx",
+    # Use this for dev testing:
+    # base_url="https://gateway-dpkhzbkdjj.cn-hangzhou.fcapp.run",
+)
+
+result = client.translate.text(
+    "Welcome to Yunmao Open Platform.",
+    target_language="ug",
+    source_language="auto",
+)
+print(result["translated_text"])
+```
+
+The default `base_url` is `https://api.xjymai.com`. Do not use production API keys for development tests; pass the dev gateway `base_url` with a dev API key.
+
+## Examples
+
+```python
+client.translate.text("hello", target_language="ug")
+```
+
+```python
+client.tts.synthesize(
+    "欢迎使用云猫开放平台。",
+    voice_id="voice_id_here",
+    language_code="zh",
+    speed=1.0,
+)
+```
+
+```python
+client.asr.recognize(
+    "/path/to/audio.wav",
+    language_hint="mul_cn",
+    sample_rate=16000,
+)
+```
+
+```python
+client.video.parse(url="https://v.douyin.com/example/")
+```
+
+```python
+client.oil.price(province="新疆")
+```
+
+```python
+client.voices.clone(
+    name="Demo voice",
+    language_code="zh",
+    ref_text="这是样本音频中的朗读文本。",
+    sample_url="https://oss.example.com/sample.wav",
+)
+```
+
+## Errors
+
+```python
+from yunmao import YunmaoAPIError
+
+try:
+    client.translate.text("hello", target_language="ug")
+except YunmaoAPIError as error:
+    print(error.status_code)
+    print(error.code)
+    print(error.message)
+    print(error.request_id)
+```
+
+The SDK preserves:
+
+- `status_code`: HTTP status
+- `code`: Yunmao business error code
+- `message`: server `msg`
+- `request_id`: from `X-Request-ID`, `request_id`, or `requestId` when the server provides it
+- `response_body`: parsed raw response body
+
+Common Open API codes:
+
+| code | HTTP | Meaning |
+| --- | --- | --- |
+| `40102` | 401 | Invalid or missing API Key |
+| `40301` | 403 | API Key scope denied |
+| `40302` | 403 | Quota exhausted |
+| `40303` | 403 | Real-name verification required |
+| `40401` | 404 | Resource not found |
+| `42201` | 422 | Invalid JSON body |
+| `42202` | 422 | Invalid parameter |
+| `42901` | 429 | Concurrency exceeded |
+| `50201` | 502 | Downstream service unavailable |
+| `50301` | 503 | Database unavailable |
+| `50000` | 500 | Internal server error |
+
+## Voice List Note
+
+The current voice list endpoint is a console JWT endpoint (`GET /api/v1/open-platform/voices`), not an API Key Open API endpoint. This SDK exposes API Key calls only, so it includes `voices.clone()` but does not expose voice listing yet. Add a server-side `GET /v1/voices` endpoint before adding that SDK method.
+
+## Test
+
+```bash
+pytest
+```
+
+Tests use `httpx.MockTransport`; they do not call dev or production paid APIs.
+
+## Publish
+
+```bash
+python -m pip install build twine
+python -m build
+twine upload dist/*
+```

yunmao-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "yunmao"
+version = "0.1.0"
+description = "Official Python SDK for Yunmao Open Platform APIs"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Yunmao" }]
+keywords = ["yunmao", "openapi", "translation", "tts", "asr"]
+dependencies = ["httpx>=0.26,<1"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://open.xjymai.com"
+Documentation = "https://open.xjymai.com/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yunmao"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

yunmao-0.1.0/src/yunmao/__init__.py

@@ -0,0 +1,4 @@
+from .client import DEFAULT_BASE_URL, YunmaoClient
+from .errors import YunmaoAPIError
+
+__all__ = ["DEFAULT_BASE_URL", "YunmaoAPIError", "YunmaoClient"]

yunmao-0.1.0/src/yunmao/client.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import json
+import mimetypes
+from pathlib import Path
+from typing import Any, BinaryIO, Mapping
+
+import httpx
+
+from .errors import YunmaoAPIError
+from .resources.asr import ASRResource
+from .resources.oil import OilResource
+from .resources.translate import TranslateResource
+from .resources.tts import TTSResource
+from .resources.video import VideoResource
+from .resources.voices import VoicesResource
+
+DEFAULT_BASE_URL = "https://api.xjymai.com"
+
+
+class YunmaoClient:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = 60.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError("api_key is required")
+
+        self.api_key = api_key.strip()
+        self.base_url = base_url.rstrip("/")
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout)
+
+        self.translate = TranslateResource(self)
+        self.tts = TTSResource(self)
+        self.asr = ASRResource(self)
+        self.video = VideoResource(self)
+        self.oil = OilResource(self)
+        self.voices = VoicesResource(self)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "YunmaoClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Mapping[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+        files: Any = None,
+        data: Mapping[str, Any] | None = None,
+    ) -> Any:
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+
+        response = self._client.request(
+            method,
+            self._url(path),
+            headers=headers,
+            json=_compact(json_body) if json_body is not None else None,
+            params=_compact(params),
+            files=files,
+            data=_compact(data),
+        )
+        return self._parse_response(response)
+
+    def _url(self, path: str) -> str:
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        return f"{self.base_url}/{path.lstrip('/')}"
+
+    def _parse_response(self, response: httpx.Response) -> Any:
+        payload: Any
+        try:
+            payload = response.json()
+        except json.JSONDecodeError as exc:
+            raise YunmaoAPIError(
+                "服务响应格式错误",
+                status_code=response.status_code,
+                request_id=_request_id(response, None),
+                response_body=response.text,
+            ) from exc
+
+        envelope = payload if isinstance(payload, dict) and "code" in payload and "data" in payload else None
+        request_id = _request_id(response, payload)
+
+        if not response.is_success:
+            raise YunmaoAPIError(
+                _message(payload, response.reason_phrase or "请求失败"),
+                status_code=response.status_code,
+                code=_code(payload, response.status_code),
+                request_id=request_id,
+                response_body=payload,
+            )
+
+        if envelope is not None:
+            code = int(envelope.get("code") or 0)
+            if code != 0:
+                raise YunmaoAPIError(
+                    str(envelope.get("msg") or "请求失败"),
+                    status_code=response.status_code,
+                    code=code,
+                    request_id=request_id,
+                    response_body=payload,
+                )
+            return envelope.get("data")
+
+        return payload
+
+
+def _compact(values: Mapping[str, Any] | None) -> dict[str, Any] | None:
+    if not values:
+        return None
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def _message(payload: Any, fallback: str) -> str:
+    if isinstance(payload, dict):
+        value = payload.get("msg") or payload.get("message") or payload.get("error")
+        if value:
+            return str(value)
+    return fallback
+
+
+def _code(payload: Any, fallback: int) -> int:
+    if isinstance(payload, dict):
+        value = payload.get("code")
+        if isinstance(value, int):
+            return value
+    return fallback
+
+
+def _request_id(response: httpx.Response, payload: Any) -> str | None:
+    for header in ("X-Request-ID", "X-Request-Id", "x-request-id", "Request-Id"):
+        value = response.headers.get(header)
+        if value:
+            return value
+    if isinstance(payload, dict):
+        value = payload.get("request_id") or payload.get("requestId")
+        if value:
+            return str(value)
+    return None
+
+
+def build_audio_file(
+    audio_file: str | Path | bytes | BinaryIO,
+    *,
+    filename: str | None = None,
+    content_type: str | None = None,
+) -> tuple[str, Any, str | None]:
+    if isinstance(audio_file, (str, Path)):
+        path = Path(audio_file)
+        guessed_type = content_type or mimetypes.guess_type(path.name)[0]
+        return path.name, path.open("rb"), guessed_type
+    if isinstance(audio_file, bytes):
+        name = filename or "audio.wav"
+        guessed_type = content_type or mimetypes.guess_type(name)[0]
+        return name, audio_file, guessed_type
+    name = filename or getattr(audio_file, "name", None) or "audio.wav"
+    guessed_type = content_type or mimetypes.guess_type(str(name))[0]
+    return Path(str(name)).name, audio_file, guessed_type

yunmao-0.1.0/src/yunmao/errors.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class YunmaoAPIError(Exception):
+    """Error returned by Yunmao Open Platform or raised while parsing a response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: int | None = None,
+        request_id: str | None = None,
+        response_body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.response_body = response_body
+
+    def __repr__(self) -> str:
+        return (
+            "YunmaoAPIError("
+            f"message={self.message!r}, status_code={self.status_code!r}, "
+            f"code={self.code!r}, request_id={self.request_id!r})"
+        )

yunmao-0.1.0/src/yunmao/resources/__init__.py

@@ -0,0 +1 @@
+

yunmao-0.1.0/src/yunmao/resources/asr.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, BinaryIO
+
+from ..types import ASRResponse
+
+if TYPE_CHECKING:
+    from ..client import YunmaoClient
+
+
+class ASRResource:
+    def __init__(self, client: "YunmaoClient") -> None:
+        self._client = client
+
+    def recognize(
+        self,
+        audio_file: str | Path | bytes | BinaryIO,
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+        language_hint: str | None = None,
+        audio_format: str | None = None,
+        sample_rate: int | None = None,
+        audio_duration_ms: int | None = None,
+    ) -> ASRResponse:
+        from ..client import build_audio_file
+
+        file_name, file_content, guessed_type = build_audio_file(
+            audio_file,
+            filename=filename,
+            content_type=content_type,
+        )
+        should_close = hasattr(file_content, "close")
+        try:
+            files = {"audio_file": (file_name, file_content, guessed_type)}
+            data = {
+                "language_hint": language_hint,
+                "audio_format": audio_format,
+                "sample_rate": sample_rate,
+                "audio_duration_ms": audio_duration_ms,
+            }
+            return self._client.request("POST", "/v1/asr/recognize", files=files, data=data)
+        finally:
+            if should_close:
+                file_content.close()

yunmao-0.1.0/src/yunmao/resources/oil.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..types import OilPriceResponse
+
+if TYPE_CHECKING:
+    from ..client import YunmaoClient
+
+
+class OilResource:
+    def __init__(self, client: "YunmaoClient") -> None:
+        self._client = client
+
+    def price(
+        self,
+        *,
+        province: str | None = None,
+        region_name: str | None = None,
+        region_code: str | None = None,
+    ) -> OilPriceResponse:
+        return self._client.request(
+            "GET",
+            "/v1/oil/price",
+            params={"province": province, "region_name": region_name, "region_code": region_code},
+        )

yunmao-0.1.0/src/yunmao/resources/translate.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..types import TranslateTextResponse
+
+if TYPE_CHECKING:
+    from ..client import YunmaoClient
+
+
+class TranslateResource:
+    def __init__(self, client: "YunmaoClient") -> None:
+        self._client = client
+
+    def text(
+        self,
+        text: str,
+        *,
+        target_language: str,
+        source_language: str | None = None,
+        direction: str | None = None,
+    ) -> TranslateTextResponse:
+        return self._client.request(
+            "POST",
+            "/v1/translate/text",
+            json_body={
+                "text": text,
+                "target_language": target_language,
+                "source_language": source_language,
+                "direction": direction,
+            },
+        )

yunmao-0.1.0/src/yunmao/resources/tts.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..types import TTSResponse
+
+if TYPE_CHECKING:
+    from ..client import YunmaoClient
+
+
+class TTSResource:
+    def __init__(self, client: "YunmaoClient") -> None:
+        self._client = client
+
+    def synthesize(
+        self,
+        text: str,
+        *,
+        voice_id: str | None = None,
+        language_code: str | None = None,
+        speed: float | None = None,
+        duration_seconds: float | None = None,
+    ) -> TTSResponse:
+        return self._client.request(
+            "POST",
+            "/v1/tts/synthesize",
+            json_body={
+                "text": text,
+                "voice_id": voice_id,
+                "language_code": language_code,
+                "speed": speed,
+                "duration_seconds": duration_seconds,
+            },
+        )

yunmao-0.1.0/src/yunmao/resources/video.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..types import VideoParseResponse
+
+if TYPE_CHECKING:
+    from ..client import YunmaoClient
+
+
+class VideoResource:
+    def __init__(self, client: "YunmaoClient") -> None:
+        self._client = client
+
+    def parse(self, *, url: str | None = None, content: str | None = None) -> VideoParseResponse:
+        return self._client.request(
+            "POST",
+            "/v1/video/parse",
+            json_body={"url": url, "content": content},
+        )

yunmao-0.1.0/src/yunmao/resources/voices.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..types import VoiceCloneResponse
+
+if TYPE_CHECKING:
+    from ..client import YunmaoClient
+
+
+class VoicesResource:
+    def __init__(self, client: "YunmaoClient") -> None:
+        self._client = client
+
+    def clone(
+        self,
+        *,
+        name: str,
+        ref_text: str,
+        language_code: str | None = None,
+        icon_url: str | None = None,
+        sample_object_key: str | None = None,
+        sample_url: str | None = None,
+    ) -> VoiceCloneResponse:
+        return self._client.request(
+            "POST",
+            "/v1/voice/clone",
+            json_body={
+                "name": name,
+                "language_code": language_code,
+                "ref_text": ref_text,
+                "icon_url": icon_url,
+                "sample_object_key": sample_object_key,
+                "sample_url": sample_url,
+            },
+        )

yunmao-0.1.0/src/yunmao/types.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+
+class Usage(TypedDict):
+    unit: str
+    amount: int
+
+
+class TranslationVariant(TypedDict):
+    id: str
+    label: str
+    translated_text: str
+
+
+class TranslateTextResponse(TypedDict, total=False):
+    id: str
+    source_language: str
+    target_language: str
+    source_text: str
+    translated_text: str
+    translation_variants: List[TranslationVariant]
+    usage: Usage
+
+
+class TTSResponse(TypedDict, total=False):
+    id: str
+    voice_id: str
+    language_code: str
+    text: str
+    audio_url: str
+    audio_format: str
+    sample_rate: Optional[int]
+    audio_duration_ms: Optional[int]
+    usage: Usage
+
+
+class ASRResponse(TypedDict, total=False):
+    id: str
+    language_hint: str
+    recognized_text: str
+    audio_format: str
+    sample_rate: int
+    audio_duration_ms: Optional[int]
+    status: str
+    usage: Usage
+
+
+class VideoParseResponse(TypedDict, total=False):
+    id: str
+    source_url: str
+    resolved_url: Optional[str]
+    platform: Optional[str]
+    content_type: Optional[str]
+    title: Optional[str]
+    description: Optional[str]
+    author_name: Optional[str]
+    author_avatar_url: Optional[str]
+    cover_url: Optional[str]
+    video_url: Optional[str]
+    audio_url: Optional[str]
+    duration_seconds: Optional[int]
+    image_count: int
+    images: List[Dict[str, Any]]
+    status: str
+    usage: Usage
+
+
+class OilPriceResponse(TypedDict, total=False):
+    region_name: str
+    fuel_grade: str
+    fuel_price: str
+    fuel_details: List[Dict[str, Any]]
+    currency: str
+    source_mode: str
+    fuel_updated_date: Optional[str]
+    items: List[Dict[str, Any]]
+    fetched_at: Optional[str]
+    usage: Usage
+
+
+class VoiceAsset(TypedDict, total=False):
+    voice_id: str
+    organization_id: Optional[str]
+    name: str
+    voice_type: str
+    language_code: Optional[str]
+    icon_url: Optional[str]
+    ref_text: Optional[str]
+    sample_object_key: Optional[str]
+    sample_url: Optional[str]
+    preview_audio_url: Optional[str]
+    status: str
+    is_default: bool
+    sort_order: int
+    created_at: str
+    updated_at: str
+
+
+class VoiceEntitlement(TypedDict, total=False):
+    max_voice_count: int
+    used_voice_count: int
+    remaining_clone_count: int
+
+
+class VoiceCloneResponse(TypedDict, total=False):
+    voice: VoiceAsset
+    entitlement: VoiceEntitlement

yunmao-0.1.0/tests/test_client.py

@@ -0,0 +1,93 @@
+import json
+
+import httpx
+import pytest
+
+from yunmao import YunmaoAPIError, YunmaoClient
+
+
+def make_client(handler):
+    transport = httpx.MockTransport(handler)
+    return YunmaoClient(
+        "ym_sk_test",
+        base_url="https://dev.example.com",
+        http_client=httpx.Client(transport=transport),
+    )
+
+
+def test_translate_sends_auth_and_unwraps_envelope():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url == "https://dev.example.com/v1/translate/text"
+        assert request.headers["authorization"] == "Bearer ym_sk_test"
+        assert json.loads(request.content) == {"text": "hello", "target_language": "ug"}
+        return httpx.Response(
+            200,
+            json={
+                "code": 0,
+                "msg": "ok",
+                "data": {"translated_text": "ياخشىمۇسىز", "usage": {"unit": "character", "amount": 5}},
+            },
+        )
+
+    client = make_client(handler)
+    result = client.translate.text("hello", target_language="ug")
+
+    assert result["translated_text"] == "ياخشىمۇسىز"
+
+
+def test_tts_accepts_direct_success_payload():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={"audio_url": "https://oss.example.com/a.wav"})
+
+    client = make_client(handler)
+    result = client.tts.synthesize("hi", voice_id="voice_1")
+
+    assert result["audio_url"] == "https://oss.example.com/a.wav"
+
+
+def test_error_preserves_status_code_code_msg_request_id_and_body():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            403,
+            headers={"X-Request-ID": "req_123"},
+            json={"code": 40302, "msg": "额度不足", "data": None},
+        )
+
+    client = make_client(handler)
+
+    with pytest.raises(YunmaoAPIError) as exc_info:
+        client.oil.price(province="新疆")
+
+    error = exc_info.value
+    assert error.status_code == 403
+    assert error.code == 40302
+    assert error.message == "额度不足"
+    assert error.request_id == "req_123"
+    assert error.response_body["code"] == 40302
+
+
+def test_asr_uploads_multipart_audio_file():
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = request.content
+        assert b'name="audio_file"; filename="sample.wav"' in body
+        assert b'name="language_hint"' in body
+        assert b"mul_cn" in body
+        return httpx.Response(200, json={"recognized_text": "hello", "usage": {"unit": "minute", "amount": 1}})
+
+    client = make_client(handler)
+    result = client.asr.recognize(b"RIFF....", filename="sample.wav", language_hint="mul_cn")
+
+    assert result["recognized_text"] == "hello"
+
+
+def test_video_and_voice_paths():
+    seen_paths = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen_paths.append(request.url.path)
+        return httpx.Response(200, json={"code": 0, "msg": "ok", "data": {"ok": True}})
+
+    client = make_client(handler)
+    assert client.video.parse(url="https://v.example")["ok"] is True
+    assert client.voices.clone(name="demo", ref_text="hello", sample_url="https://oss.example/a.wav")["ok"] is True
+    assert seen_paths == ["/v1/video/parse", "/v1/voice/clone"]