From 78088a18cba9026b9d22825c96cbf536e1f5b88f Mon Sep 17 00:00:00 2001
From: fishaudio-bot <242899544+fishaudio-bot@users.noreply.github.com>
Date: Sat, 21 Feb 2026 11:26:19 +0000
Subject: [PATCH] chore: update Python SDK API reference
Auto-generated from fishaudio/fish-audio-python@dd251bf89560486099a6ad765bb73731b7aaba19
---
api-reference/sdk/python/core.mdx | 308 ++++++++++++-------------
api-reference/sdk/python/resources.mdx | 296 ++++++++++++------------
api-reference/sdk/python/types.mdx | 112 ++++-----
api-reference/sdk/python/utils.mdx | 76 +++---
4 files changed, 396 insertions(+), 396 deletions(-)
diff --git a/api-reference/sdk/python/core.mdx b/api-reference/sdk/python/core.mdx
index 8d594f1..121df42 100644
--- a/api-reference/sdk/python/core.mdx
+++ b/api-reference/sdk/python/core.mdx
@@ -1,153 +1,8 @@
-
-
-# fishaudio.core.client\_wrapper
-
-HTTP client wrapper for managing requests and authentication.
-
-
-
-## BaseClientWrapper Objects
-
-```python
-class BaseClientWrapper()
-```
-
-Base wrapper with shared logic for sync/async clients.
-
-
-
-#### get\_headers
-
-```python
-def get_headers(
- additional_headers: Optional[dict[str, str]] = None) -> dict[str, str]
-```
-
-Build headers including authentication and user agent.
-
-
-
-## ClientWrapper Objects
-
-```python
-class ClientWrapper(BaseClientWrapper)
-```
-
-Wrapper for httpx.Client that handles authentication and error handling.
-
-
-
-#### request
-
-```python
-def request(method: str,
- path: str,
- *,
- request_options: Optional[RequestOptions] = None,
- **kwargs: Any) -> httpx.Response
-```
-
-Make an HTTP request with error handling.
-
-**Arguments**:
-
-- `method` - HTTP method (GET, POST, etc.)
-- `path` - API endpoint path
-- `request_options` - Optional request-level overrides
-- `**kwargs` - Additional arguments to pass to httpx.request
-
-
-**Returns**:
-
- httpx.Response object
-
-
-**Raises**:
-
-- `APIError` - On non-2xx responses
-
-
-
-#### client
-
-```python
-@property
-def client() -> httpx.Client
-```
-
-Get underlying httpx.Client for advanced usage (e.g., WebSockets).
-
-
-
-#### close
-
-```python
-def close() -> None
-```
-
-Close the HTTP client.
-
-
-
-## AsyncClientWrapper Objects
-
-```python
-class AsyncClientWrapper(BaseClientWrapper)
-```
-
-Wrapper for httpx.AsyncClient that handles authentication and error handling.
-
-
-
-#### request
-
-```python
-async def request(method: str,
- path: str,
- *,
- request_options: Optional[RequestOptions] = None,
- **kwargs: Any) -> httpx.Response
-```
-
-Make an async HTTP request with error handling.
-
-**Arguments**:
-
-- `method` - HTTP method (GET, POST, etc.)
-- `path` - API endpoint path
-- `request_options` - Optional request-level overrides
-- `**kwargs` - Additional arguments to pass to httpx.request
-
-
-**Returns**:
-
- httpx.Response object
-
-
-**Raises**:
-
-- `APIError` - On non-2xx responses
-
-
-
-#### client
-
-```python
-@property
-def client() -> httpx.AsyncClient
-```
-
-Get underlying httpx.AsyncClient for advanced usage (e.g., WebSockets).
-
-
-
-#### close
+
-```python
-async def close() -> None
-```
+# fishaudio.core.omit
-Close the HTTP client.
+OMIT sentinel for distinguishing None from not-provided parameters.
@@ -346,6 +201,157 @@ After calling this method, the iterator cannot be used again.
f.write(audio)
```
+
+
+# fishaudio.core.client\_wrapper
+
+HTTP client wrapper for managing requests and authentication.
+
+
+
+## BaseClientWrapper Objects
+
+```python
+class BaseClientWrapper()
+```
+
+Base wrapper with shared logic for sync/async clients.
+
+
+
+#### get\_headers
+
+```python
+def get_headers(
+ additional_headers: Optional[dict[str, str]] = None) -> dict[str, str]
+```
+
+Build headers including authentication and user agent.
+
+
+
+## ClientWrapper Objects
+
+```python
+class ClientWrapper(BaseClientWrapper)
+```
+
+Wrapper for httpx.Client that handles authentication and error handling.
+
+
+
+#### request
+
+```python
+def request(method: str,
+ path: str,
+ *,
+ request_options: Optional[RequestOptions] = None,
+ **kwargs: Any) -> httpx.Response
+```
+
+Make an HTTP request with error handling.
+
+**Arguments**:
+
+- `method` - HTTP method (GET, POST, etc.)
+- `path` - API endpoint path
+- `request_options` - Optional request-level overrides
+- `**kwargs` - Additional arguments to pass to httpx.request
+
+
+**Returns**:
+
+ httpx.Response object
+
+
+**Raises**:
+
+- `APIError` - On non-2xx responses
+
+
+
+#### client
+
+```python
+@property
+def client() -> httpx.Client
+```
+
+Get underlying httpx.Client for advanced usage (e.g., WebSockets).
+
+
+
+#### close
+
+```python
+def close() -> None
+```
+
+Close the HTTP client.
+
+
+
+## AsyncClientWrapper Objects
+
+```python
+class AsyncClientWrapper(BaseClientWrapper)
+```
+
+Wrapper for httpx.AsyncClient that handles authentication and error handling.
+
+
+
+#### request
+
+```python
+async def request(method: str,
+ path: str,
+ *,
+ request_options: Optional[RequestOptions] = None,
+ **kwargs: Any) -> httpx.Response
+```
+
+Make an async HTTP request with error handling.
+
+**Arguments**:
+
+- `method` - HTTP method (GET, POST, etc.)
+- `path` - API endpoint path
+- `request_options` - Optional request-level overrides
+- `**kwargs` - Additional arguments to pass to httpx.request
+
+
+**Returns**:
+
+ httpx.Response object
+
+
+**Raises**:
+
+- `APIError` - On non-2xx responses
+
+
+
+#### client
+
+```python
+@property
+def client() -> httpx.AsyncClient
+```
+
+Get underlying httpx.AsyncClient for advanced usage (e.g., WebSockets).
+
+
+
+#### close
+
+```python
+async def close() -> None
+```
+
+Close the HTTP client.
+
# fishaudio.core.websocket\_options
@@ -394,9 +400,3 @@ def to_httpx_ws_kwargs() -> dict[str, Any]
Convert to kwargs dict for httpx_ws aconnect_ws/connect_ws.
-
-
-# fishaudio.core.omit
-
-OMIT sentinel for distinguishing None from not-provided parameters.
-
diff --git a/api-reference/sdk/python/resources.mdx b/api-reference/sdk/python/resources.mdx
index 4e94445..5b25574 100644
--- a/api-reference/sdk/python/resources.mdx
+++ b/api-reference/sdk/python/resources.mdx
@@ -312,163 +312,65 @@ async def delete(voice_id: str,
Delete a voice (async). See sync version for details.
-
-
-# fishaudio.resources.account
-
-Account namespace client for billing and credits.
-
-
-
-## AccountClient Objects
+
-```python
-class AccountClient()
-```
+# fishaudio.resources.realtime
-Synchronous account operations.
+Real-time WebSocket streaming helpers.
-
+
-#### get\_credits
+#### iter\_websocket\_audio
```python
-def get_credits(*,
- check_free_credit: Optional[bool] = OMIT,
- request_options: Optional[RequestOptions] = None) -> Credits
+def iter_websocket_audio(ws) -> Iterator[bytes]
```
-Get API credit balance.
-
-**Arguments**:
-
-- `check_free_credit` - Whether to check free credit availability
-- `request_options` - Request-level overrides
-
-
-**Returns**:
-
- Credits information
-
-
-**Example**:
-
- ```python
- client = FishAudio(api_key="...")
- credits = client.account.get_credits()
- print(f"Available credits: {float(credits.credit)}")
-
- # Check free credit availability
- credits = client.account.get_credits(check_free_credit=True)
- if credits.has_free_credit:
- print("Free credits available!")
- ```
-
-
-
-#### get\_package
-
-```python
-def get_package(*,
- request_options: Optional[RequestOptions] = None) -> Package
-```
+Process WebSocket audio messages (sync).
-Get package information.
+Receives messages from WebSocket, yields audio chunks, handles errors.
+Unknown events are ignored and iteration continues.
**Arguments**:
-- `request_options` - Request-level overrides
+- `ws` - WebSocket connection from httpx_ws.connect_ws
-**Returns**:
+**Yields**:
- Package information
+ Audio bytes
-**Example**:
-
- ```python
- client = FishAudio(api_key="...")
- package = client.account.get_package()
- print(f"Balance: {package.balance}/{package.total}")
- ```
-
-
-
-## AsyncAccountClient Objects
-
-```python
-class AsyncAccountClient()
-```
+**Raises**:
-Asynchronous account operations.
+- `WebSocketError` - On disconnect or error finish event
-
+
-#### get\_credits
+#### aiter\_websocket\_audio
```python
-async def get_credits(
- *,
- check_free_credit: Optional[bool] = OMIT,
- request_options: Optional[RequestOptions] = None) -> Credits
+async def aiter_websocket_audio(ws) -> AsyncIterator[bytes]
```
-Get API credit balance (async).
-
-**Arguments**:
-
-- `check_free_credit` - Whether to check free credit availability
-- `request_options` - Request-level overrides
-
-
-**Returns**:
-
- Credits information
-
-
-**Example**:
-
- ```python
- client = AsyncFishAudio(api_key="...")
- credits = await client.account.get_credits()
- print(f"Available credits: {float(credits.credit)}")
-
- # Check free credit availability
- credits = await client.account.get_credits(check_free_credit=True)
- if credits.has_free_credit:
- print("Free credits available!")
- ```
-
-
-
-#### get\_package
-
-```python
-async def get_package(*,
- request_options: Optional[RequestOptions] = None
- ) -> Package
-```
+Process WebSocket audio messages (async).
-Get package information (async).
+Receives messages from WebSocket, yields audio chunks, handles errors.
+Unknown events are ignored and iteration continues.
**Arguments**:
-- `request_options` - Request-level overrides
+- `ws` - WebSocket connection from httpx_ws.aconnect_ws
-**Returns**:
+**Yields**:
- Package information
+ Audio bytes
-**Example**:
+**Raises**:
- ```python
- client = AsyncFishAudio(api_key="...")
- package = await client.account.get_package()
- print(f"Balance: {package.balance}/{package.total}")
- ```
+- `WebSocketError` - On disconnect or error finish event
@@ -924,65 +826,163 @@ Perfect for conversational AI, live captioning, and streaming applications.
await f.write(audio_chunk)
```
-
+
-# fishaudio.resources.realtime
+# fishaudio.resources.account
-Real-time WebSocket streaming helpers.
+Account namespace client for billing and credits.
-
+
-#### iter\_websocket\_audio
+## AccountClient Objects
```python
-def iter_websocket_audio(ws) -> Iterator[bytes]
+class AccountClient()
```
-Process WebSocket audio messages (sync).
+Synchronous account operations.
-Receives messages from WebSocket, yields audio chunks, handles errors.
-Unknown events are ignored and iteration continues.
+
+
+#### get\_credits
+
+```python
+def get_credits(*,
+ check_free_credit: Optional[bool] = OMIT,
+ request_options: Optional[RequestOptions] = None) -> Credits
+```
+
+Get API credit balance.
**Arguments**:
-- `ws` - WebSocket connection from httpx_ws.connect_ws
+- `check_free_credit` - Whether to check free credit availability
+- `request_options` - Request-level overrides
-**Yields**:
+**Returns**:
- Audio bytes
+ Credits information
-**Raises**:
+**Example**:
-- `WebSocketError` - On disconnect or error finish event
+ ```python
+ client = FishAudio(api_key="...")
+ credits = client.account.get_credits()
+ print(f"Available credits: {float(credits.credit)}")
-
+ # Check free credit availability
+ credits = client.account.get_credits(check_free_credit=True)
+ if credits.has_free_credit:
+ print("Free credits available!")
+ ```
-#### aiter\_websocket\_audio
+
+
+#### get\_package
```python
-async def aiter_websocket_audio(ws) -> AsyncIterator[bytes]
+def get_package(*,
+ request_options: Optional[RequestOptions] = None) -> Package
```
-Process WebSocket audio messages (async).
+Get package information.
-Receives messages from WebSocket, yields audio chunks, handles errors.
-Unknown events are ignored and iteration continues.
+**Arguments**:
+
+- `request_options` - Request-level overrides
+
+
+**Returns**:
+
+ Package information
+
+
+**Example**:
+
+ ```python
+ client = FishAudio(api_key="...")
+ package = client.account.get_package()
+ print(f"Balance: {package.balance}/{package.total}")
+ ```
+
+
+
+## AsyncAccountClient Objects
+
+```python
+class AsyncAccountClient()
+```
+
+Asynchronous account operations.
+
+
+
+#### get\_credits
+
+```python
+async def get_credits(
+ *,
+ check_free_credit: Optional[bool] = OMIT,
+ request_options: Optional[RequestOptions] = None) -> Credits
+```
+
+Get API credit balance (async).
**Arguments**:
-- `ws` - WebSocket connection from httpx_ws.aconnect_ws
+- `check_free_credit` - Whether to check free credit availability
+- `request_options` - Request-level overrides
-**Yields**:
+**Returns**:
- Audio bytes
+ Credits information
-**Raises**:
+**Example**:
-- `WebSocketError` - On disconnect or error finish event
+ ```python
+ client = AsyncFishAudio(api_key="...")
+ credits = await client.account.get_credits()
+ print(f"Available credits: {float(credits.credit)}")
+
+ # Check free credit availability
+ credits = await client.account.get_credits(check_free_credit=True)
+ if credits.has_free_credit:
+ print("Free credits available!")
+ ```
+
+
+
+#### get\_package
+
+```python
+async def get_package(*,
+ request_options: Optional[RequestOptions] = None
+ ) -> Package
+```
+
+Get package information (async).
+
+**Arguments**:
+
+- `request_options` - Request-level overrides
+
+
+**Returns**:
+
+ Package information
+
+
+**Example**:
+
+ ```python
+ client = AsyncFishAudio(api_key="...")
+ package = await client.account.get_package()
+ print(f"Balance: {package.balance}/{package.total}")
+ ```
diff --git a/api-reference/sdk/python/types.mdx b/api-reference/sdk/python/types.mdx
index aaf96cb..7ac0e21 100644
--- a/api-reference/sdk/python/types.mdx
+++ b/api-reference/sdk/python/types.mdx
@@ -73,53 +73,6 @@ Represents a TTS voice that can be used for synthesis.
- `marked` - Whether the current user has bookmarked this model. Default: False
- `author` - Information about the voice model's creator
-
-
-# fishaudio.types.account
-
-Account-related types (credits, packages, etc.).
-
-
-
-## Credits Objects
-
-```python
-class Credits(BaseModel)
-```
-
-User's API credit balance.
-
-**Attributes**:
-
-- `id` - Unique credits record identifier
-- `user_id` - User identifier
-- `credit` - Current credit balance (decimal for precise accounting)
-- `created_at` - Timestamp when the credits record was created
-- `updated_at` - Timestamp when the credits were last updated
-- `has_phone_sha256` - Whether the user has a verified phone number. Optional
-- `has_free_credit` - Whether the user has received free credits. Optional
-
-
-
-## Package Objects
-
-```python
-class Package(BaseModel)
-```
-
-User's prepaid package information.
-
-**Attributes**:
-
-- `id` - Unique package identifier
-- `user_id` - User identifier
-- `type` - Package type identifier
-- `total` - Total units in the package
-- `balance` - Remaining units in the package
-- `created_at` - Timestamp when the package was purchased
-- `updated_at` - Timestamp when the package was last updated
-- `finished_at` - Timestamp when the package was fully consumed. None if still active
-
# fishaudio.types.tts
@@ -312,26 +265,52 @@ WebSocket event to end the streaming session.
- `event` - Event type identifier, always "stop"
-
+
-# fishaudio.types.shared
+# fishaudio.types.account
-Shared types used across the SDK.
+Account-related types (credits, packages, etc.).
-
+
-## PaginatedResponse Objects
+## Credits Objects
```python
-class PaginatedResponse(BaseModel, Generic[T])
+class Credits(BaseModel)
```
-Generic paginated response.
+User's API credit balance.
**Attributes**:
-- `total` - Total number of items across all pages
-- `items` - List of items on the current page
+- `id` - Unique credits record identifier
+- `user_id` - User identifier
+- `credit` - Current credit balance (decimal for precise accounting)
+- `created_at` - Timestamp when the credits record was created
+- `updated_at` - Timestamp when the credits were last updated
+- `has_phone_sha256` - Whether the user has a verified phone number. Optional
+- `has_free_credit` - Whether the user has received free credits. Optional
+
+
+
+## Package Objects
+
+```python
+class Package(BaseModel)
+```
+
+User's prepaid package information.
+
+**Attributes**:
+
+- `id` - Unique package identifier
+- `user_id` - User identifier
+- `type` - Package type identifier
+- `total` - Total units in the package
+- `balance` - Remaining units in the package
+- `created_at` - Timestamp when the package was purchased
+- `updated_at` - Timestamp when the package was last updated
+- `finished_at` - Timestamp when the package was fully consumed. None if still active
@@ -377,3 +356,24 @@ Response from speech-to-text transcription.
Duration in milliseconds
+
+
+# fishaudio.types.shared
+
+Shared types used across the SDK.
+
+
+
+## PaginatedResponse Objects
+
+```python
+class PaginatedResponse(BaseModel, Generic[T])
+```
+
+Generic paginated response.
+
+**Attributes**:
+
+- `total` - Total number of items across all pages
+- `items` - List of items on the current page
+
diff --git a/api-reference/sdk/python/utils.mdx b/api-reference/sdk/python/utils.mdx
index 30f93ea..100aa97 100644
--- a/api-reference/sdk/python/utils.mdx
+++ b/api-reference/sdk/python/utils.mdx
@@ -1,3 +1,41 @@
+
+
+# fishaudio.utils.save
+
+Audio saving utility.
+
+
+
+#### save
+
+```python
+def save(audio: Union[bytes, Iterable[bytes]], filename: str) -> None
+```
+
+Save audio to a file.
+
+**Arguments**:
+
+- `audio` - Audio bytes or iterable of bytes
+- `filename` - Path to save the audio file
+
+
+**Examples**:
+
+ ```python
+ from fishaudio import FishAudio, save
+
+ client = FishAudio(api_key="...")
+ audio = client.tts.convert(text="Hello world")
+
+ # Save to file
+ save(audio, "output.mp3")
+
+ # Works with iterators too
+ audio_stream = client.tts.convert(text="Another example")
+ save(audio_stream, "another.mp3")
+ ```
+
# fishaudio.utils.play
@@ -47,44 +85,6 @@ Play audio using various playback methods.
play(audio, use_ffmpeg=False)
```
-
-
-# fishaudio.utils.save
-
-Audio saving utility.
-
-
-
-#### save
-
-```python
-def save(audio: Union[bytes, Iterable[bytes]], filename: str) -> None
-```
-
-Save audio to a file.
-
-**Arguments**:
-
-- `audio` - Audio bytes or iterable of bytes
-- `filename` - Path to save the audio file
-
-
-**Examples**:
-
- ```python
- from fishaudio import FishAudio, save
-
- client = FishAudio(api_key="...")
- audio = client.tts.convert(text="Hello world")
-
- # Save to file
- save(audio, "output.mp3")
-
- # Works with iterators too
- audio_stream = client.tts.convert(text="Another example")
- save(audio_stream, "another.mp3")
- ```
-
# fishaudio.utils.stream