uapi-sdk-python 0.1.15__tar.gz → 0.1.17__tar.gz

{uapi_sdk_python-0.1.15 → uapi_sdk_python-0.1.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uapi-sdk-python
-Version: 0.1.15
+Version: 0.1.17
 Summary: Idiomatic UAPI SDK for Python
 Author-email: UAPI <dev@uapis.cn>
 Requires-Python: >=3.9

{uapi_sdk_python-0.1.15 → uapi_sdk_python-0.1.17}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "uapi-sdk-python"
-version = "0.1.15"
+version = "0.1.17"
 description = "Idiomatic UAPI SDK for Python"
 readme = "README.md"
 requires-python = ">=3.9"

{uapi_sdk_python-0.1.15 → uapi_sdk_python-0.1.17}/uapi/client.py

@@ -3,6 +3,7 @@ from dataclasses import dataclass
 from typing import Any, Dict, Optional
 import httpx
 import time
+from pathlib import Path
 
 from .errors import *
 # internal models live under ./internal (generated by openapi-generator-cli)
@@ -37,6 +38,31 @@ def _coerce_optional_bool(value: Any) -> Optional[bool]:
         return bool(value)
     return bool(value)
 
+
+def _stringify_form_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _prepare_file_value(value: Any):
+    if isinstance(value, (str, Path)):
+        path = Path(value)
+        if not path.is_file():
+            raise FileNotFoundError(f"File not found: {path}")
+        return (path.name, path.read_bytes())
+    if isinstance(value, (bytes, bytearray)):
+        return ("upload.bin", bytes(value))
+    if isinstance(value, tuple):
+        return value
+    if hasattr(value, "read"):
+        content = value.read()
+        if isinstance(content, str):
+            content = content.encode("utf-8")
+        file_name = Path(getattr(value, "name", "upload.bin")).name
+        return (file_name or "upload.bin", content)
+    raise TypeError(f"Unsupported multipart file value: {type(value)!r}")
+
 class _HTTP:
     def __init__(self, cfg: _Config):
         self._cfg = cfg
@@ -62,6 +88,8 @@ class _HTTP:
         *,
         params: Dict[str, Any] | None = None,
         json: Any | None = None,
+        data: Dict[str, Any] | None = None,
+        files: Dict[str, Any] | None = None,
         headers: Dict[str, str] | None = None,
         disable_cache: bool | None = None,
     ):
@@ -70,7 +98,7 @@ class _HTTP:
         if self._cfg.token:
             headers["Authorization"] = f"Bearer {self._cfg.token}"
         query = self._apply_cache_control(method, params, disable_cache)
-        r = self._client.request(method, url, params=query, json=json, headers=headers)
+        r = self._client.request(method, url, params=query, json=json, data=data, files=files, headers=headers)
         if r.status_code >= 400:
             err = map_error(r)
             self.last_response_meta = err.meta
@@ -464,7 +492,9 @@ class _GameApi:
         想在加入服务器前看看有多少人在线？或者检查一下服务器开没开？用这个接口就对了！
 
 ## 功能概述
-你可以通过提供服务器地址（域名或IP），来获取一个 Minecraft Java 版服务器的实时状态。返回信息非常丰富，包括服务器是否在线、当前玩家数、最大玩家数、服务器版本、MOTD（每日消息）以及服务器图标等。
+你可以通过提供服务器地址（域名或IP），来获取一个 Minecraft Java 版服务器的实时状态。返回信息包括服务器是否在线、当前玩家数、最大玩家数、服务器版本、MOTD（每日消息）以及服务器图标等。
+
+如果服务器返回当前在线玩家列表，响应里还会带上 `online_players` 字段。这个字段可能省略，部分服务器返回的列表也可能不完整。
         """
         params = {}
         body = {}
@@ -533,8 +563,8 @@ class _GameApi:
 ## 使用须知
 
 > [!IMPORTANT]
-> **API Key 安全**
-> 此接口需要一个 Steam Web API Key。我们强烈建议由后端统一配置和调用，以避免在客户端泄露。当然，你也可以通过 `key` 查询参数临时提供一个Key来覆盖后端配置。
+> **访问凭证说明**
+> 这个接口可以传 `key` 使用您自己的访问凭证。如果您选择传入，请注意妥善保管，不要把它写进公开的前端代码中。
 
 在处理响应时，请注意以下数字代码的含义：
 - **`personastate` (用户状态)**: 0-离线, 1-在线, 2-忙碌, 3-离开, 4-打盹, 5-想交易, 6-想玩。
@@ -578,7 +608,7 @@ class _ImageApi:
     
     def get_avatar_gravatar(self, **kwargs):
         r"""获取Gravatar头像
-        提供一个超高速、高可用的Gravatar头像代理服务。内置了强大的ETag条件缓存，确保用户在更新Gravatar头像后能几乎立刻看到变化，同时最大化地利用缓存。
+        提供稳定、易用的头像获取能力，适合在网页或应用中直接展示头像。
         """
         params = {}
         body = {}
@@ -614,18 +644,32 @@ class _ImageApi:
         )
     
     def get_image_bing_daily(self, **kwargs):
-        r"""必应壁纸
-        每天都想换张新壁纸？让必应的美图点亮你的一天吧！
+        r"""获取必应每日壁纸
+        这个接口可以获取最新或指定日期的必应壁纸。默认直接返回图片，也可以传 `format=json` 获取元数据，或者传 `format=redirect` 直接跳转到最终图片地址。
 
 ## 功能概述
-这个接口会获取 Bing 搜索引擎当天全球同步的每日壁纸，并直接以图片形式返回。你可以用它来做应用的启动页、网站背景，或者任何需要每日更新精美图片的地方。
+- 不传参数时，默认返回当天壁纸图片二进制
+- 可以传 `date` 查询指定日期的壁纸
+- 可以传 `resolution` 选择 `4k` 或 `1080`
+- 可以传 `format` 控制返回图片、JSON 或 302 跳转
+- 当传 `format=json` 时，返回的是扁平 JSON 对象，里面会包含标题、副标题、说明文案、版权信息、问答信息和图片地址等字段
 
-## 使用须知
-此接口成功时直接返回图片二进制数据，通常是 `image/jpeg`，不是 JSON 格式。接入时请按图片响应来处理。
+## 参数说明
+`resolution` 默认是 `4k`。
+`format` 默认是 `image`。
         """
         params = {}
         body = {}
         
+        if "query" == "query" and "date" in kwargs:
+            params["date"] = kwargs["date"]
+        
+        if "query" == "query" and "resolution" in kwargs:
+            params["resolution"] = kwargs["resolution"]
+        
+        if "query" == "query" and "format" in kwargs:
+            params["format"] = kwargs["format"]
+        
         if "_t" in kwargs:
             params["_t"] = kwargs["_t"]
         disable_cache = kwargs.get("disable_cache")
@@ -641,6 +685,52 @@ class _ImageApi:
             disable_cache=_coerce_optional_bool(disable_cache),
         )
     
+    def get_image_bing_daily_history(self, **kwargs):
+        r"""查询必应壁纸历史
+        这个接口用于查询必应壁纸历史列表，也可以按日期精确查询某一天。默认按时间倒序返回 JSON。
+
+## 功能概述
+- 可以传 `date` 精确查询某一天，命中后只返回 1 条数据
+- 不传 `date` 时，按时间倒序分页返回历史列表
+- 可以传 `resolution` 让 `image_url` 直接对应 `4k` 或 `1080`
+- 可以传 `page` 和 `page_size` 控制分页
+- 每条记录都是扁平 JSON 对象，里面会包含标题、副标题、说明文案、版权信息、问答信息和图片地址等字段
+
+## 参数说明
+`resolution` 默认是 `4k`。
+`page` 默认是 `1`，`page_size` 默认是 `30`，最大是 `100`。
+当传了 `date` 以后，`page` 和 `page_size` 不生效。
+        """
+        params = {}
+        body = {}
+        
+        if "query" == "query" and "date" in kwargs:
+            params["date"] = kwargs["date"]
+        
+        if "query" == "query" and "resolution" in kwargs:
+            params["resolution"] = kwargs["resolution"]
+        
+        if "query" == "query" and "page" in kwargs:
+            params["page"] = kwargs["page"]
+        
+        if "query" == "query" and "page_size" in kwargs:
+            params["page_size"] = kwargs["page_size"]
+        
+        if "_t" in kwargs:
+            params["_t"] = kwargs["_t"]
+        disable_cache = kwargs.get("disable_cache")
+        if disable_cache is None and "disableCache" in kwargs:
+            disable_cache = kwargs["disableCache"]
+        path = "/api/v1/image/bing-daily/history"
+        
+        return self._http.request(
+            "GET",
+            path,
+            params=params,
+            json=body if body else None,
+            disable_cache=_coerce_optional_bool(disable_cache),
+        )
+    
     def get_image_motou(self, **kwargs):
         r"""生成摸摸头GIF (QQ号)
         想在线rua一下好友的头像吗？这个趣味接口可以满足你。
@@ -756,11 +846,11 @@ class _ImageApi:
 
 ## 使用须知
 > [!TIP]
-> 为了给您最好的压缩效果，我们的算法需要进行复杂计算，处理时间可能会稍长一些，请耐心等待。
+> 图片越大或压缩等级越高，处理时间可能越长，请您耐心等待。
 
 > [!WARNING]
-> **服务排队提醒**
-> 这是一个计算密集型服务。在高并发时，您的请求可能会被排队等待处理。如果您需要将其集成到对延迟敏感的生产服务中，请注意这一点。
+> **处理时间提醒**
+> 在访问量较高时，处理时间可能进一步延长。如果您的业务对返回时间比较敏感，建议预留充足的处理时间。
 
 ### 请求与响应格式
 - 请求必须使用 `multipart/form-data` 格式上传文件。
@@ -780,7 +870,8 @@ class _ImageApi:
 - **500 Internal Server Error**: 如果在压缩过程中服务器发生内部错误，会返回此状态码。
         """
         params = {}
-        body = {}
+        data = {}
+        files = {}
         
         if "query" == "query" and "level" in kwargs:
             params["level"] = kwargs["level"]
@@ -792,7 +883,7 @@ class _ImageApi:
             params["_t"] = kwargs["_t"]
         
         if "file" in kwargs:
-            body["file"] = kwargs["file"]
+            files["file"] = _prepare_file_value(kwargs["file"])
         
         disable_cache = kwargs.get("disable_cache")
         if disable_cache is None and "disableCache" in kwargs:
@@ -803,7 +894,73 @@ class _ImageApi:
             "POST",
             path,
             params=params,
-            json=body if body else None,
+            data=data or None,
+            files=files or None,
+            disable_cache=_coerce_optional_bool(disable_cache),
+        )
+    
+    def post_image_decode(self, **kwargs):
+        r"""解码并缩放图片
+        在 RAM 和 Flash 极其有限的设备上解码图片是一项繁重的任务。这个接口专为 IoT 和嵌入式开发设计，将复杂的图像解码和缩放操作转移到云端，直接输出适用于单片机屏幕的二进制像素流。
+
+## 功能概述
+此接口提供了灵活的云端图像预处理能力，帮助硬件开发者跳过繁琐的图像处理逻辑：
+- **直接推流渲染**：如果选择输出纯像素流（如 RGB565），单片机收到网络数据后无需解析文件头，可直接将其写入显存，实现极低内存占用的边下边播。
+- **完美适配屏幕**：无需在设备端编写裁剪或补边代码。只需传入目标屏幕的物理分辨率，接口会自动完成等比缩放、居中补色或铺满裁剪，确保最终显示画面不变形。
+- **精准内存分配**：在动态缩放图片的场景下，服务端会在 HTTP 响应头中提前注入 `X-Image-Width` 和 `X-Image-Height`，方便设备在读取真实的二进制数据前进行准确的内存分配。
+
+## 使用须知
+- **请求格式**：无论是上传本地文件还是传递图片链接，请求体都必须使用 `multipart/form-data` 编码格式。
+- **网络资源获取**：当您选择传递图片链接时，服务端会自动尝试获取该资源。请确保您提供的图片链接是公网直接可访问的，且不需要任何形式的登录鉴权。
+        """
+        params = {}
+        data = {}
+        files = {}
+        
+        if "query" == "query" and "width" in kwargs:
+            params["width"] = kwargs["width"]
+        
+        if "query" == "query" and "height" in kwargs:
+            params["height"] = kwargs["height"]
+        
+        if "query" == "query" and "max_width" in kwargs:
+            params["max_width"] = kwargs["max_width"]
+        
+        if "query" == "query" and "max_height" in kwargs:
+            params["max_height"] = kwargs["max_height"]
+        
+        if "query" == "query" and "format" in kwargs:
+            params["format"] = kwargs["format"]
+        
+        if "query" == "query" and "color_mode" in kwargs:
+            params["color_mode"] = kwargs["color_mode"]
+        
+        if "query" == "query" and "fit" in kwargs:
+            params["fit"] = kwargs["fit"]
+        
+        if "query" == "query" and "background" in kwargs:
+            params["background"] = kwargs["background"]
+        
+        if "_t" in kwargs:
+            params["_t"] = kwargs["_t"]
+        
+        if "file" in kwargs:
+            files["file"] = _prepare_file_value(kwargs["file"])
+        
+        if "url" in kwargs:
+            data["url"] = _stringify_form_value(kwargs["url"])
+        
+        disable_cache = kwargs.get("disable_cache")
+        if disable_cache is None and "disableCache" in kwargs:
+            disable_cache = kwargs["disableCache"]
+        path = "/api/v1/image/decode"
+        
+        return self._http.request(
+            "POST",
+            path,
+            params=params,
+            data=data or None,
+            files=files or None,
             disable_cache=_coerce_optional_bool(disable_cache),
         )
     
@@ -857,19 +1014,20 @@ class _ImageApi:
 - **背景颜色**：同样支持 `bg_color` 表单字段来控制GIF背景。
         """
         params = {}
-        body = {}
+        data = {}
+        files = {}
         
         if "_t" in kwargs:
             params["_t"] = kwargs["_t"]
         
         if "bg_color" in kwargs:
-            body["bg_color"] = kwargs["bg_color"]
+            data["bg_color"] = _stringify_form_value(kwargs["bg_color"])
         
         if "file" in kwargs:
-            body["file"] = kwargs["file"]
+            files["file"] = _prepare_file_value(kwargs["file"])
         
         if "image_url" in kwargs:
-            body["image_url"] = kwargs["image_url"]
+            data["image_url"] = _stringify_form_value(kwargs["image_url"])
         
         disable_cache = kwargs.get("disable_cache")
         if disable_cache is None and "disableCache" in kwargs:
@@ -880,7 +1038,8 @@ class _ImageApi:
             "POST",
             path,
             params=params,
-            json=body if body else None,
+            data=data or None,
+            files=files or None,
             disable_cache=_coerce_optional_bool(disable_cache),
         )
     
@@ -908,16 +1067,17 @@ class _ImageApi:
 - **inference_time_ms**: 模型推理耗时，单位毫秒
         """
         params = {}
-        body = {}
+        data = {}
+        files = {}
         
         if "_t" in kwargs:
             params["_t"] = kwargs["_t"]
         
         if "file" in kwargs:
-            body["file"] = kwargs["file"]
+            files["file"] = _prepare_file_value(kwargs["file"])
         
         if "url" in kwargs:
-            body["url"] = kwargs["url"]
+            data["url"] = _stringify_form_value(kwargs["url"])
         
         disable_cache = kwargs.get("disable_cache")
         if disable_cache is None and "disableCache" in kwargs:
@@ -928,7 +1088,63 @@ class _ImageApi:
             "POST",
             path,
             params=params,
-            json=body if body else None,
+            data=data or None,
+            files=files or None,
+            disable_cache=_coerce_optional_bool(disable_cache),
+        )
+    
+    def post_image_ocr(self, **kwargs):
+        r"""通用 OCR 文字识别
+        无论您是需要实现票据的自动化录入，还是在网页前端对图片上的文字进行坐标框选，这个高精度的 OCR 接口都能为您提供强大的基础能力。
+
+## 功能概述
+> [!IMPORTANT]
+> 如果您只关心图片上写了什么（例如截图取字或内容安全审核），强烈建议将 `need_location` 设置为 `false`。这会大幅精简返回的 JSON 数据体积，提升网络传输与系统解析效率。
+
+除了常规的图片转文字，这个接口还针对实际开发场景做了一些实用设计：
+- **前端文字高亮与结构化分析**：默认返回每一段文字的矩形坐标和四个顶点坐标。这非常适合使用 Canvas 在原图上画框高亮，或者在后端根据相对位置提取票据中的键值对信息。
+- **复杂拍摄环境下的抗畸变**：针对手机拍摄导致的旋转或倾斜，可以开启 `enable_cls=true`。服务端在识别前会自动进行方向预校正，显著提升识别准确率。
+- **灵活的输入与请求要求**：接口支持 `file`、`url` 或 `image_base64` 三种方式输入。请确保请求格式为 `multipart/form-data`，且图片链接在公网可直接访问。
+        """
+        params = {}
+        data = {}
+        files = {}
+        
+        if "_t" in kwargs:
+            params["_t"] = kwargs["_t"]
+        
+        if "enable_cls" in kwargs:
+            data["enable_cls"] = _stringify_form_value(kwargs["enable_cls"])
+        
+        if "file" in kwargs:
+            files["file"] = _prepare_file_value(kwargs["file"])
+        
+        if "image_base64" in kwargs:
+            data["image_base64"] = _stringify_form_value(kwargs["image_base64"])
+        
+        if "image_name" in kwargs:
+            data["image_name"] = _stringify_form_value(kwargs["image_name"])
+        
+        if "need_location" in kwargs:
+            data["need_location"] = _stringify_form_value(kwargs["need_location"])
+        
+        if "return_markdown" in kwargs:
+            data["return_markdown"] = _stringify_form_value(kwargs["return_markdown"])
+        
+        if "url" in kwargs:
+            data["url"] = _stringify_form_value(kwargs["url"])
+        
+        disable_cache = kwargs.get("disable_cache")
+        if disable_cache is None and "disableCache" in kwargs:
+            disable_cache = kwargs["disableCache"]
+        path = "/api/v1/image/ocr"
+        
+        return self._http.request(
+            "POST",
+            path,
+            params=params,
+            data=data or None,
+            files=files or None,
             disable_cache=_coerce_optional_bool(disable_cache),
         )
     
@@ -974,7 +1190,8 @@ class _ImageApi:
 上传一个 SVG 文件，并指定目标格式（如 PNG、JPEG 等），接口将返回转换后的图像。你还可以调整输出图像的尺寸和（对于JPEG）压缩质量，以满足不同场景的需求。
         """
         params = {}
-        body = {}
+        data = {}
+        files = {}
         
         if "query" == "query" and "format" in kwargs:
             params["format"] = kwargs["format"]
@@ -992,7 +1209,7 @@ class _ImageApi:
             params["_t"] = kwargs["_t"]
         
         if "file" in kwargs:
-            body["file"] = kwargs["file"]
+            files["file"] = _prepare_file_value(kwargs["file"])
         
         disable_cache = kwargs.get("disable_cache")
         if disable_cache is None and "disableCache" in kwargs:
@@ -1003,7 +1220,8 @@ class _ImageApi:
             "POST",
             path,
             params=params,
-            json=body if body else None,
+            data=data or None,
+            files=files or None,
             disable_cache=_coerce_optional_bool(disable_cache),
         )
     
@@ -1136,6 +1354,8 @@ class _MiscApi:
 如果你只关心某一类事件，可以通过 `holiday_type` 进行筛选，例如只看法定休假/调休、公历节日、农历节日或节气。
 
 在 `date` 模式下，传 `include_nearby=true` 可以额外返回该日期前后最近的节日；返回数量由 `nearby_limit` 控制，默认 7，最大 30。
+
+如果你只想保留今天和之后的节日，可以再传 `exclude_past=true` 过滤已经过去的节日。
         """
         params = {}
         body = {}
@@ -1161,6 +1381,9 @@ class _MiscApi:
         if "query" == "query" and "nearby_limit" in kwargs:
             params["nearby_limit"] = kwargs["nearby_limit"]
         
+        if "query" == "query" and "exclude_past" in kwargs:
+            params["exclude_past"] = kwargs["exclude_past"]
+        
         if "_t" in kwargs:
             params["_t"] = kwargs["_t"]
         disable_cache = kwargs.get("disable_cache")
@@ -1193,9 +1416,6 @@ class _MiscApi:
 
 ### 搜索模式
 传 `type` + `keyword` + `time_start` + `time_end` 参数，在指定时间范围内搜索包含关键词的热榜条目。可选传 `limit` 限制返回数量。
-
-### 数据源列表
-传 `sources=true`，返回所有支持历史数据的平台列表。
         """
         params = {}
         body = {}
@@ -1218,9 +1438,6 @@ class _MiscApi:
         if "query" == "query" and "limit" in kwargs:
             params["limit"] = kwargs["limit"]
         
-        if "query" == "query" and "sources" in kwargs:
-            params["sources"] = kwargs["sources"]
-        
         if "_t" in kwargs:
             params["_t"] = kwargs["_t"]
         disable_cache = kwargs.get("disable_cache")
@@ -1464,14 +1681,12 @@ graph TD
         买了东西想知道快递到哪儿了？这个接口帮你实时追踪物流状态。
 
 ## 功能概述
-提供一个快递单号，系统会自动识别快递公司并返回完整的物流轨迹信息。这个接口目前可以查询中通、圆通、韵达、申通、极兔、京东、EMS、德邦等主流快递公司的物流信息。
+提供一个快递单号，系统会自动识别快递公司并返回完整的物流轨迹信息。这个接口目前可以查询中通、圆通、韵达、申通、极兔、顺丰、京东、EMS、德邦等主流快递公司的物流信息。
 
 ## 使用须知
-目前暂不支持顺丰快递单号的物流查询。
-
 - **自动识别**：不知道是哪家快递？系统会根据单号规则自动识别快递公司（推荐使用）
 - **手动指定**：如果已知快递公司，可以传递 `carrier_code` 参数，查询速度会更快
-- **手机尾号验证**：部分快递公司需要验证收件人手机尾号才能查询详细物流，如果返回 `暂无物流信息`，建议尝试传入 `phone` 参数
+- **手机尾号验证**：顺丰等部分快递公司需要验证收件人手机尾号才能查询详细物流，如果返回 `暂无物流信息`，建议尝试传入 `phone` 参数
 - **查询时效**：物流信息实时查询，响应时间通常在1-2秒内
         """
         params = {}
@@ -1486,6 +1701,9 @@ graph TD
         if "query" == "query" and "phone" in kwargs:
             params["phone"] = kwargs["phone"]
         
+        if "query" == "query" and "full" in kwargs:
+            params["full"] = kwargs["full"]
+        
         if "_t" in kwargs:
             params["_t"] = kwargs["_t"]
         disable_cache = kwargs.get("disable_cache")
@@ -1709,12 +1927,12 @@ class _NetworkApi:
     
     def get_network_ipinfo(self, **kwargs):
         r"""查询 IP
-        想知道一个IP地址或域名来自地球的哪个角落？这个接口可以帮你定位它。你可以使用默认数据源，也可以指定 `source=commercial` 参数来查询更详细的商业级IP归属信息。
+        想知道一个IP地址或域名来自哪里？这个接口可以帮你定位它。默认返回标准结果；如果传 `source=commercial`，可以返回更完整的位置信息。
 
 ## 功能概述
 提供一个公网IPv4、IPv6地址或域名，我们会查询并返回它的地理位置（国家、省份、城市）、经纬度、以及所属的运营商（ISP）和自治系统（ASN）信息。这在网络安全分析、访问来源统计等领域非常有用。
 
-当使用 `source=commercial` 参数时，接口将调用高性能商业API，提供更精确的市、区、运营商、时区、海拔等信息。请注意，商业查询的响应时间可能会稍长。
+当传 `source=commercial` 时，响应中会补充更完整的市、区、运营商、时区、海拔等信息，响应时间可能会稍长。
         """
         params = {}
         body = {}
@@ -1742,12 +1960,12 @@ class _NetworkApi:
     
     def get_network_myip(self, **kwargs):
         r"""查询我的 IP
-        想知道你自己的出口公网IP是多少吗？这个接口就是你的“网络身份证”。你可以使用默认数据源，也可以指定 `source=commercial` 参数来查询更详细的商业级IP归属信息。
+        想知道你自己的出口公网IP是多少吗？这个接口就是你的“网络身份证”。默认返回标准结果；如果传 `source=commercial`，可以返回更完整的位置信息。
 
 ## 功能概述
 调用此接口，它会返回你（即发起请求的客户端）的公网IP地址，并附带与 `/network/ipinfo` 接口相同的地理位置和网络归属信息。非常适合用于在网页上向用户展示他们自己的IP和地理位置。
 
-当使用 `source=commercial` 参数时，接口将调用高性能商业API，提供更精确的市、区、运营商、时区、海拔等信息。请注意，商业查询的响应时间可能会稍长。
+当传 `source=commercial` 时，响应中会补充更完整的市、区、运营商、时区、海拔等信息，响应时间可能会稍长。
         """
         params = {}
         body = {}
@@ -2174,19 +2392,16 @@ class _SocialApi:
     
     def get_github_repo(self, **kwargs):
         r"""查询 GitHub 仓库
-        需要快速获取一个GitHub仓库的核心信息？这个接口为你聚合了最有价值的数据，避免了多次调用GitHub官方API的麻烦，并且内置了缓存优化，速度更快、更稳定。
+        需要快速获取一个GitHub仓库的核心信息？这个接口一次请求就能返回仓库的关键数据，适合项目展示、统计和分析场景。
 
-### 聚合高价值数据
+### 可获取的数据
 一次请求，即可获得以下信息：
 - **核心指标**: `star`, `fork`, `open_issues` 等关键统计数据。
 - **项目详情**: 描述、主页、分支、语言、话题标签、开源协议。
-- **参与者信息**: 获取协作者(`collaborators`)和推断的维护者(`maintainers`)列表，包括他们的公开邮箱（如果可用）。
+- **参与者信息**: 获取协作者(`collaborators`)和维护者参考信息(`maintainers`)列表，包括他们的公开邮箱（如果可用）。
 
 > [!NOTE]
-> `collaborators` 字段在私有仓库或权限受限时可能为空。`maintainers` 是根据最新提交记录推断的，仅供参考。
-
-### 性能与稳定性
-我们内置了多级缓存，有效避免触发GitHub的API速率限制。对于需要更高请求额度的用户，可以联系我们定制接口。
+> `collaborators` 字段在私有仓库或权限受限时可能为空。`maintainers` 为整理后的参考信息，仅供参考。
         """
         params = {}
         body = {}
@@ -2209,6 +2424,45 @@ class _SocialApi:
             disable_cache=_coerce_optional_bool(disable_cache),
         )
     
+    def get_github_user(self, **kwargs):
+        r"""查询 GitHub 用户信息
+        需要获取开发者的 GitHub 画像？这个接口不仅能返回详尽的基础资料和所属的公开组织列表，还能一键拉取开发者的绿格子数据。
+
+## 功能概述
+- **开发者基础画像**：返回用户的仓库数、关注数、公司、地理位置和社交媒体链接等，非常适合用来自动生成技术博客的作者名片或建立开发者档案。
+- **贡献日历与时间线**：只要开启 `activity=true`，就能获取该用户最近一年的全量贡献数据。返回的 JSON 已经将数据按周（weeks）和天（days）整理好，前端通过简单的双重循环就能画出和 GitHub 主页一模一样的贡献日历。
+- **组织级贡献过滤**：如果你只想评估某个人在特定团队开源项目中的活跃度，直接传入 `org` 参数。接口会自动剥离他在其他私有项目或个人仓库的提交，只返回针对该组织的贡献数据。
+        """
+        params = {}
+        body = {}
+        
+        if "query" == "query" and "user" in kwargs:
+            params["user"] = kwargs["user"]
+        
+        if "query" == "query" and "activity" in kwargs:
+            params["activity"] = kwargs["activity"]
+        
+        if "query" == "query" and "activity_scope" in kwargs:
+            params["activity_scope"] = kwargs["activity_scope"]
+        
+        if "query" == "query" and "org" in kwargs:
+            params["org"] = kwargs["org"]
+        
+        if "_t" in kwargs:
+            params["_t"] = kwargs["_t"]
+        disable_cache = kwargs.get("disable_cache")
+        if disable_cache is None and "disableCache" in kwargs:
+            disable_cache = kwargs["disableCache"]
+        path = "/api/v1/github/user"
+        
+        return self._http.request(
+            "GET",
+            path,
+            params=params,
+            json=body if body else None,
+            disable_cache=_coerce_optional_bool(disable_cache),
+        )
+    
     def get_social_bilibili_archives(self, **kwargs):
         r"""查询 B站投稿
         想要获取UP主的所有投稿视频？或者想在你的应用里展示创作者的作品集？这个接口能帮你轻松实现。
@@ -2475,15 +2729,15 @@ class _SocialApi:
     
     def get_social_qq_userinfo(self, **kwargs):
         r"""查询 QQ 信息
-        这是一个功能丰富的QQ用户信息查询接口，能够获取QQ用户的详细公开信息。
+        通过 QQ 号查询用户资料，返回头像、昵称、个性签名、等级和 VIP 信息。
 
 ## 功能概述
-通过QQ号查询用户的详细信息，包括基础资料、等级信息、VIP状态等。返回的信息丰富全面，适合用于用户画像分析、社交应用集成等场景。
+这个接口适合用在用户资料展示、头像卡片、账号绑定结果展示等场景。若用户把 QQ 等级设为隐藏，`qq_level` 会返回 `null`。
 
 ## 数据字段说明
 - **基础信息**: 昵称、个性签名、头像、年龄、性别
-- **联系信息**: QQ邮箱、个性域名(QID)
-- **等级信息**: QQ等级、VIP状态和等级
+- **联系信息**: QQ 邮箱、个性域名（QID）
+- **等级信息**: QQ 等级、VIP 状态和等级
 - **时间信息**: 注册时间、最后更新时间
         """
         params = {}
@@ -2515,10 +2769,10 @@ class _StatusApi:
     
     def get_status_ratelimit(self, **kwargs):
         r"""限流状态
-        想了解我们API的当前负载情况吗？这个接口为你提供了服务的“心电图”。
+        想了解当前服务的运行状态吗？这个接口可以返回关键监控指标。
 
 ## 功能概述
-此接口返回我们后端自适应限流器的实时状态。你可以看到当前并发请求数、并发上限、系统负载、请求接受/拒绝数等核心指标。这对于监控API健康状况和性能表现至关重要。
+此接口用于查看当前服务状态，包括并发请求数、当前限制值、系统负载等信息，适合管理员排查运行情况。
 
 > [!IMPORTANT]
 > 此接口为管理接口，需要提供有效的管理员级别API密钥才能访问。
@@ -2792,7 +3046,7 @@ class _TextApi:
 
 ### 输出格式支持
 - **base64**（默认）：标准Base64编码输出，适合传输和存储
-- **hex**：十六进制编码输出，方便与在线加密工具对比验证
+- **hex**：十六进制编码输出，方便进行结果核对
 
 通过 `output_format` 参数可以直接获取HEX格式的密文，无需额外调用转换接口。
 
@@ -2847,7 +3101,6 @@ class _TextApi:
 - **加密算法**: AES-256
 - **编码格式**: Base64/HEX（输入/输出）
 - **IV长度**: 16字节（128位）
-- **版本标注**: v3.4.8+
 
 > [!NOTE]
 > **关于IV（初始化向量）**
@@ -2858,7 +3111,7 @@ class _TextApi:
 
 > [!TIP]
 > **关于输出格式**
-> - 如需与在线加密工具（如 toolhelper.cn）对比结果，建议使用 `output_format: "hex"` 
+> - 如需核对输出结果，建议使用 `output_format: "hex"`
 > - Base64格式更适合网络传输和API调用
 > - 两种格式可以相互转换，数据完全一致
         """
@@ -3032,6 +3285,84 @@ class _TextApi:
             disable_cache=_coerce_optional_bool(disable_cache),
         )
     
+    def post_text_markdown_to_html(self, **kwargs):
+        r"""Markdown 转 HTML
+        直接调用这个接口，就可以把 Markdown 文本转换成带样式的 HTML，而且它不只适合程序里动态注入，也适合在开发阶段直接预览。
+
+## 如何使用与预览
+- **默认模式：返回 JSON 里的 HTML 片段**：不传 `format` 时，接口会返回 JSON。您只需要读取响应里的 `data.html`，再赋值给前端容器，例如 `element.innerHTML = data.html`、Vue 的 `v-html`，或者 React 里配合 `dangerouslySetInnerHTML` 使用。
+- **预览模式：直接返回完整 HTML 网页**：如果您想在浏览器里直接打开结果，或者想把响应保存成一个独立的 `.html` 文件，请传 `format="html"`。这个模式下，接口会直接返回带 `<!DOCTYPE html><html>...` 的完整网页源码。
+
+## 功能概述
+- **自带精美排版，无需手写 CSS**：返回结果已经内置样式，标题、引用、表格、任务列表和代码块都可以直接显示。
+- **支持丰富的排版元素**：除了标准 Markdown，这个接口也可以正确处理 GFM 常见语法，例如表格、任务列表和带语言标记的代码块。
+- **安全处理用户内容**：默认开启安全模式，会自动过滤原始 HTML 里的风险脚本。如果内容来源绝对可信，并且您确实需要保留原始 HTML，可以把 `sanitize` 设为 `false`。
+        """
+        params = {}
+        body = {}
+        
+        if "_t" in kwargs:
+            params["_t"] = kwargs["_t"]
+        
+        if "format" in kwargs:
+            body["format"] = kwargs["format"]
+        
+        if "sanitize" in kwargs:
+            body["sanitize"] = kwargs["sanitize"]
+        
+        if "text" in kwargs:
+            body["text"] = kwargs["text"]
+        
+        disable_cache = kwargs.get("disable_cache")
+        if disable_cache is None and "disableCache" in kwargs:
+            disable_cache = kwargs["disableCache"]
+        path = "/api/v1/text/markdown-to-html"
+        
+        return self._http.request(
+            "POST",
+            path,
+            params=params,
+            json=body if body else None,
+            disable_cache=_coerce_optional_bool(disable_cache),
+        )
+    
+    def post_text_markdown_to_pdf(self, **kwargs):
+        r"""Markdown 转 PDF
+        当您的业务系统需要提供“导出为 PDF”的功能时，无需在后端部署复杂的排版引擎，只需将 Markdown 文本发给这个接口，即可直接获取打印级的 PDF 文件。
+
+## 功能概述
+- **服务端直接生成**：接口直接返回 PDF 文件二进制流，前端无需任何处理即可触发下载，后端也能轻松存盘归档。
+- **多种精美主题与纸张**：内置了 GitHub、暗黑等多种专业排版主题，并支持 A4、Letter 等标准纸张。只需简单配置，就能生成符合业务场景的专业文档。
+- **公网图片也可以直接带入 PDF**：除了纯文本和标准 Markdown 语法，这个接口也可以处理 `data URI` 图片，或者公网可访问的 `http`、`https` 图片链接。服务端会先通过代理抓取图片，并在渲染前内联到文档里，同时带有超时控制。
+        """
+        params = {}
+        body = {}
+        
+        if "_t" in kwargs:
+            params["_t"] = kwargs["_t"]
+        
+        if "paper_size" in kwargs:
+            body["paper_size"] = kwargs["paper_size"]
+        
+        if "text" in kwargs:
+            body["text"] = kwargs["text"]
+        
+        if "theme" in kwargs:
+            body["theme"] = kwargs["theme"]
+        
+        disable_cache = kwargs.get("disable_cache")
+        if disable_cache is None and "disableCache" in kwargs:
+            disable_cache = kwargs["disableCache"]
+        path = "/api/v1/text/markdown-to-pdf"
+        
+        return self._http.request(
+            "POST",
+            path,
+            params=params,
+            json=body if body else None,
+            disable_cache=_coerce_optional_bool(disable_cache),
+        )
+    
     def post_text_md_5(self, **kwargs):
         r"""MD5 哈希 (POST)
         一个用于计算文本 MD5 哈希值的标准工具，推荐使用此版本。
@@ -3123,7 +3454,7 @@ class _TranslateApi:
     
     def post_ai_translate(self, **kwargs):
         r"""AI智能翻译
-        这是一个商业级的AI智能翻译服务，采用最新的神经网络翻译技术和大语言模型，提供远超传统机器翻译的质量。
+        这是一个高质量的智能翻译服务，支持多种翻译风格和专业场景，适合对译文质量有更高要求的业务场景。
 
 ## 功能概述
 
@@ -3432,8 +3763,8 @@ class _MinGanCiShiBieApi:
 
 ## 功能概述
 
-- **模型驱动**: 使用先进的分析模型进行语义分析。
-- **高性能**: 采用三级缓存策略（持久化存储 → 统一缓存 → 模型分析），确保高频请求的响应速度。
+- **风险分析**: 结合文本内容给出语义层面的风险判断。
+- **响应稳定**: 兼顾高频调用场景下的处理效率和响应速度。
 - **并发支持**: 支持批量并发处理，单次最多可分析100个关键词。
 - **输入限制**: 单条关键词最多 1,000 字符，总字符数最多 20,000。
 - **标准标签**: 返回 `label` 字段，明确区分 `sensitive` 与 `normal`。
@@ -3476,18 +3807,18 @@ class _MinGanCiShiBieApi:
     
     def post_sensitive_word_quick_check(self, **kwargs):
         r"""敏感词检测（快速）
-        在你的社区或应用中，需要来过滤掉不和谐的声音吗？这个接口可以助你一臂之力。
+        在你的社区或应用中，需要过滤不适合展示的内容时，这个接口可以帮你快速完成检测。
 
 ## 功能概述
 
-我们对敏感词检测接口进行了大幅升级，现在采用高效的 **Aho-Corasick 算法**，实现了多模式字符串匹配。这意味着你不再需要手动编写复杂的正则表达式，系统会自动高效地检测出文本中的所有敏感词。
+这个接口可以识别文本中的敏感词，并返回是否命中、命中词列表等结果，适合用于评论区、社区、论坛和内容发布场景。
 
 ### 主要特性
 
-- **高性能算法**：基于 Aho-Corasick 算法，单次扫描即可检测多个敏感词模式
-- **简繁体支持**：自动识别和处理简体中文、繁体中文内容
-- **多模匹配**：无需编写正则表达式，系统内置智能匹配逻辑
-- **快速响应**：相比传统方法，检测速度显著提升
+- **快速检测**：能够一次处理整段文本中的多个命中内容
+- **简繁体支持**：支持简体中文、繁体中文和混合文本检测
+- **结果直观**：返回清晰的检测结果，方便直接接入审核流程
+- **响应稳定**：适合日常内容审核和批量检查场景
 
 无论是论坛、社交平台还是评论系统，这个接口都能帮你快速构建内容审核功能。
         """
@@ -3521,14 +3852,14 @@ class _ZhiNengSouSuoApi:
     
     def get_search_engines(self, **kwargs):
         r"""搜索引擎配置
-        获取 UAPI Pro Search 引擎的详细信息，包括支持的功能特性、参数限制和使用说明。
+        获取搜索功能的详细信息，包括支持的能力、参数限制和使用说明。
 
 ## 功能概述
 
-此接口返回搜索引擎的完整配置信息，你可以用它来：
-- 了解搜索引擎支持哪些功能（如站内搜索、文件类型过滤等）
+此接口返回搜索功能的完整配置信息，你可以用它来：
+- 了解当前可用的搜索能力（如站内搜索、文件类型过滤等）
 - 获取参数的默认值和限制范围
-- 查看当前引擎版本和可用状态
+- 查看当前配置版本和可用状态
 
 适合在应用初始化时调用，或用于动态配置搜索界面。
       
@@ -3553,14 +3884,14 @@ class _ZhiNengSouSuoApi:
     
     def post_search_aggregate(self, **kwargs):
         r"""智能搜索
-        想在你的应用中集成搜索功能？我们提供了一个强大的搜索引擎API，让你可以轻松实现实时网页搜索。
+        想在你的应用中集成搜索功能？这个接口可以帮你轻松实现实时网页搜索。
 
 ## 功能概述
 
-UAPI Pro Search 是一个智能搜索引擎，采用机器学习算法对搜索结果进行智能排序，确保最相关的内容排在前面。你可以用它搜索任何关键词，也可以限定在特定网站或特定文件类型中搜索。
+UAPI Pro Search 可以根据查询内容返回更相关的搜索结果。你可以用它搜索任何关键词，也可以限定在特定网站或特定文件类型中搜索。
 
 - **实时网页搜索**: 毫秒级响应，快速返回搜索结果
-- **智能排序**: 采用机器学习回归排序算法，结果更精准
+- **智能排序**: 根据查询内容返回更相关的结果
 - **时间排序**: 支持按发布时间排序，获取最新内容
 - **时间范围过滤**: 支持按天/周/月/年过滤结果
 - **站内搜索**: 支持 `site:` 操作符，在指定网站内搜索
@@ -3591,9 +3922,6 @@ UAPI Pro Search 是一个智能搜索引擎，采用机器学习算法对搜索
         if "time_range" in kwargs:
             body["time_range"] = kwargs["time_range"]
         
-        if "timeout_ms" in kwargs:
-            body["timeout_ms"] = kwargs["timeout_ms"]
-        
         disable_cache = kwargs.get("disable_cache")
         if disable_cache is None and "disableCache" in kwargs:
             disable_cache = kwargs["disableCache"]

{uapi_sdk_python-0.1.15 → uapi_sdk_python-0.1.17}/uapi/errors.py

@@ -67,7 +67,7 @@ class UapiError(Exception):
 
 class ApiErrorError(UapiError):
     """上游/内部错误 (API_ERROR)"""
-    DEFAULT_STATUS = 502
+    DEFAULT_STATUS = 504
 
 class AvatarNotFoundError(UapiError):
     """头像未找到 (AVATAR_NOT_FOUND)"""

{uapi_sdk_python-0.1.15 → uapi_sdk_python-0.1.17}/uapi_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uapi-sdk-python
-Version: 0.1.15
+Version: 0.1.17
 Summary: Idiomatic UAPI SDK for Python
 Author-email: UAPI <dev@uapis.cn>
 Requires-Python: >=3.9