vectorvein 0.1.95__py3-none-any.whl → 0.2.1__py3-none-any.whl

vectorvein/api/__init__.py

@@ -0,0 +1,36 @@
+"""向量脉络 API 包"""
+
+from .client import VectorVeinClient, AsyncVectorVeinClient
+from .models import (
+    VApp,
+    AccessKey,
+    WorkflowInputField,
+    WorkflowOutput,
+    WorkflowRunResult,
+    AccessKeyListResponse,
+)
+from .exceptions import (
+    VectorVeinAPIError,
+    APIKeyError,
+    WorkflowError,
+    AccessKeyError,
+    RequestError,
+    TimeoutError,
+)
+
+__all__ = [
+    "VectorVeinClient",
+    "AsyncVectorVeinClient",
+    "VApp",
+    "AccessKey",
+    "WorkflowInputField",
+    "WorkflowOutput",
+    "WorkflowRunResult",
+    "AccessKeyListResponse",
+    "VectorVeinAPIError",
+    "APIKeyError",
+    "WorkflowError",
+    "AccessKeyError",
+    "RequestError",
+    "TimeoutError",
+]

vectorvein/api/client.py

@@ -0,0 +1,827 @@
+"""向量脉络 API 客户端"""
+
+import time
+import base64
+import asyncio
+from urllib.parse import quote
+from typing import List, Optional, Dict, Any, Union, Literal, overload
+
+import httpx
+from Crypto.Cipher import AES
+from Crypto.Util.Padding import pad
+
+from .exceptions import (
+    VectorVeinAPIError,
+    APIKeyError,
+    WorkflowError,
+    AccessKeyError,
+    RequestError,
+    TimeoutError,
+)
+from .models import (
+    AccessKey,
+    WorkflowInputField,
+    WorkflowOutput,
+    WorkflowRunResult,
+    AccessKeyListResponse,
+)
+
+
+class VectorVeinClient:
+    """向量脉络 API 客户端类"""
+
+    API_VERSION = "20240508"
+    BASE_URL = "https://vectorvein.com/api/v1/open-api"
+
+    def __init__(self, api_key: str, base_url: Optional[str] = None):
+        """初始化客户端
+
+        Args:
+            api_key: API密钥
+            base_url: API基础URL，默认为https://vectorvein.com/api/v1/open-api
+
+        Raises:
+            APIKeyError: API密钥为空或格式不正确
+        """
+        if not api_key or not isinstance(api_key, str):
+            raise APIKeyError("API密钥不能为空且必须是字符串类型")
+
+        self.api_key = api_key
+        self.base_url = base_url or self.BASE_URL
+        self._client = httpx.Client(
+            headers={
+                "VECTORVEIN-API-KEY": api_key,
+                "VECTORVEIN-API-VERSION": self.API_VERSION,
+            }
+        )
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._client.close()
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """发送HTTP请求
+
+        Args:
+            method: HTTP方法
+            endpoint: API端点
+            params: URL参数
+            json: JSON请求体
+            **kwargs: 其他请求参数
+
+        Returns:
+            Dict[str, Any]: API响应
+
+        Raises:
+            RequestError: 请求错误
+            VectorVeinAPIError: API错误
+            APIKeyError: API密钥无效或已过期
+        """
+        url = f"{self.base_url}/{endpoint}"
+        try:
+            response = self._client.request(method=method, url=url, params=params, json=json, **kwargs)
+            response.raise_for_status()
+            result = response.json()
+
+            if result["status"] in [401, 403]:
+                raise APIKeyError("API密钥无效或已过期")
+            if result["status"] != 200 and result["status"] != 202:
+                raise VectorVeinAPIError(message=result.get("msg", "Unknown error"), status_code=result["status"])
+            return result
+        except httpx.HTTPError as e:
+            raise RequestError(f"Request failed: {str(e)}")
+
+    @overload
+    def run_workflow(
+        self,
+        wid: str,
+        input_fields: List[WorkflowInputField],
+        output_scope: Literal["all", "output_fields_only"] = "output_fields_only",
+        wait_for_completion: Literal[False] = False,
+        timeout: int = 30,
+    ) -> str: ...
+
+    @overload
+    def run_workflow(
+        self,
+        wid: str,
+        input_fields: List[WorkflowInputField],
+        output_scope: Literal["all", "output_fields_only"] = "output_fields_only",
+        wait_for_completion: Literal[True] = True,
+        timeout: int = 30,
+    ) -> WorkflowRunResult: ...
+
+    def run_workflow(
+        self,
+        wid: str,
+        input_fields: List[WorkflowInputField],
+        output_scope: Literal["all", "output_fields_only"] = "output_fields_only",
+        wait_for_completion: bool = False,
+        timeout: int = 30,
+    ) -> Union[str, WorkflowRunResult]:
+        """运行工作流
+
+        Args:
+            wid: 工作流ID
+            input_fields: 输入字段列表
+            output_scope: 输出范围，可选值：'all' 或 'output_fields_only'
+            wait_for_completion: 是否等待完成
+            timeout: 超时时间（秒）
+
+        Returns:
+            Union[str, WorkflowRunResult]: 工作流运行ID或运行结果
+
+        Raises:
+            WorkflowError: 工作流运行错误
+            TimeoutError: 超时错误
+        """
+        payload = {
+            "wid": wid,
+            "output_scope": output_scope,
+            "wait_for_completion": wait_for_completion,
+            "input_fields": [
+                {"node_id": field.node_id, "field_name": field.field_name, "value": field.value}
+                for field in input_fields
+            ],
+        }
+
+        result = self._request("POST", "workflow/run", json=payload)
+
+        if not wait_for_completion:
+            return result["data"]["rid"]
+
+        rid = result.get("rid") or (isinstance(result["data"], dict) and result["data"].get("rid")) or ""
+        start_time = time.time()
+
+        while True:
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Workflow execution timed out after {timeout} seconds")
+
+            status = self.check_workflow_status(rid)
+            if status["status"] == 200:
+                return WorkflowRunResult(
+                    rid=rid,
+                    status=status["status"],
+                    msg=status["msg"],
+                    data=[WorkflowOutput(**output) for output in status["data"]],
+                )
+            elif status["status"] == 500:
+                raise WorkflowError(f"Workflow execution failed: {status['msg']}")
+
+            time.sleep(5)
+
+    def check_workflow_status(self, rid: str) -> Dict:
+        """检查工作流运行状态
+
+        Args:
+            rid: 工作流运行记录ID
+
+        Returns:
+            Dict: 工作流状态信息
+        """
+        payload = {"rid": rid}
+        return self._request("POST", "workflow/check-status", json=payload)
+
+    def get_access_keys(
+        self, access_keys: Optional[List[str]] = None, get_type: Literal["selected", "all"] = "selected"
+    ) -> List[AccessKey]:
+        """获取访问密钥信息
+
+        Args:
+            access_keys: 访问密钥列表
+            get_type: 获取类型，可选值：'selected' 或 'all'
+
+        Returns:
+            List[AccessKey]: 访问密钥信息列表
+
+        Raises:
+            AccessKeyError: 访问密钥不存在或已失效
+        """
+        params = {"get_type": get_type}
+        if access_keys:
+            params["access_keys"] = ",".join(access_keys)
+
+        try:
+            result = self._request("GET", "vapp/access-key/get", params=params)
+            return [AccessKey(**key) for key in result["data"]]
+        except VectorVeinAPIError as e:
+            if e.status_code == 404:
+                raise AccessKeyError("访问密钥不存在")
+            elif e.status_code == 403:
+                raise AccessKeyError("访问密钥已失效")
+            raise
+
+    def create_access_keys(
+        self,
+        access_key_type: Literal["O", "M", "L"],
+        app_id: Optional[str] = None,
+        app_ids: Optional[List[str]] = None,
+        count: int = 1,
+        expire_time: Optional[str] = None,
+        max_credits: Optional[int] = None,
+        max_use_count: Optional[int] = None,
+        description: Optional[str] = None,
+    ) -> List[AccessKey]:
+        """创建访问密钥
+
+        Args:
+            access_key_type: 密钥类型，可选值：'O'(一次性)、'M'(多次)、'L'(长期)
+            app_id: 单个应用ID
+            app_ids: 多个应用ID列表
+            count: 创建数量
+            expire_time: 过期时间
+            max_credits: 最大积分限制
+            max_use_count: 最大使用次数
+            description: 描述信息
+
+        Returns:
+            List[AccessKey]: 创建的访问密钥列表
+
+        Raises:
+            AccessKeyError: 创建访问密钥失败，如类型无效、应用不存在等
+        """
+        if access_key_type not in ["O", "M", "L"]:
+            raise AccessKeyError("无效的访问密钥类型，必须是 'O'(一次性)、'M'(多次) 或 'L'(长期)")
+
+        if app_id and app_ids:
+            raise AccessKeyError("不能同时指定 app_id 和 app_ids")
+
+        payload = {"access_key_type": access_key_type, "count": count}
+
+        if app_id:
+            payload["app_id"] = app_id
+        if app_ids:
+            payload["app_ids"] = app_ids
+        if expire_time:
+            payload["expire_time"] = expire_time
+        if max_credits is not None:
+            payload["max_credits"] = max_credits
+        if max_use_count is not None:
+            payload["max_use_count"] = max_use_count
+        if description:
+            payload["description"] = description
+
+        try:
+            result = self._request("POST", "vapp/access-key/create", json=payload)
+            return [AccessKey(**key) for key in result["data"]]
+        except VectorVeinAPIError as e:
+            if e.status_code == 404:
+                raise AccessKeyError("指定的应用不存在")
+            elif e.status_code == 403:
+                raise AccessKeyError("没有权限创建访问密钥")
+            raise
+
+    def list_access_keys(
+        self,
+        page: int = 1,
+        page_size: int = 10,
+        sort_field: str = "create_time",
+        sort_order: str = "descend",
+        app_id: Optional[str] = None,
+        status: Optional[List[str]] = None,
+        access_key_type: Optional[Literal["O", "M", "L"]] = None,
+    ) -> AccessKeyListResponse:
+        """列出访问密钥
+
+        Args:
+            page: 页码
+            page_size: 每页数量
+            sort_field: 排序字段
+            sort_order: 排序顺序
+            app_id: 应用ID
+            status: 状态列表
+            access_key_type: 密钥类型列表，可选值：'O'(一次性)、'M'(多次)、'L'(长期)
+
+        Returns:
+            AccessKeyListResponse: 访问密钥列表响应
+        """
+        payload = {"page": page, "page_size": page_size, "sort_field": sort_field, "sort_order": sort_order}
+
+        if app_id:
+            payload["app_id"] = app_id
+        if status:
+            payload["status"] = status
+        if access_key_type:
+            payload["access_key_type"] = access_key_type
+
+        result = self._request("POST", "vapp/access-key/list", json=payload)
+        return AccessKeyListResponse(**result["data"])
+
+    def delete_access_keys(self, app_id: str, access_keys: List[str]) -> None:
+        """删除访问密钥
+
+        Args:
+            app_id: 应用ID
+            access_keys: 要删除的访问密钥列表
+        """
+        payload = {"app_id": app_id, "access_keys": access_keys}
+        self._request("POST", "vapp/access-key/delete", json=payload)
+
+    def update_access_keys(
+        self,
+        access_key: Optional[str] = None,
+        access_keys: Optional[List[str]] = None,
+        app_id: Optional[str] = None,
+        app_ids: Optional[List[str]] = None,
+        expire_time: Optional[str] = None,
+        max_use_count: Optional[int] = None,
+        max_credits: Optional[int] = None,
+        description: Optional[str] = None,
+        access_key_type: Optional[Literal["O", "M", "L"]] = None,
+    ) -> None:
+        """更新访问密钥
+
+        Args:
+            access_key: 单个访问密钥
+            access_keys: 多个访问密钥列表
+            app_id: 单个应用ID
+            app_ids: 多个应用ID列表
+            expire_time: 过期时间
+            max_use_count: 最大使用次数
+            max_credits: 最大积分限制
+            description: 描述信息
+            access_key_type: 密钥类型，可选值：'O'(一次性)、'M'(多次)、'L'(长期)
+        """
+        payload = {}
+        if access_key:
+            payload["access_key"] = access_key
+        if access_keys:
+            payload["access_keys"] = access_keys
+        if app_id:
+            payload["app_id"] = app_id
+        if app_ids:
+            payload["app_ids"] = app_ids
+        if expire_time:
+            payload["expire_time"] = expire_time
+        if max_use_count is not None:
+            payload["max_use_count"] = max_use_count
+        if max_credits is not None:
+            payload["max_credits"] = max_credits
+        if description:
+            payload["description"] = description
+        if access_key_type:
+            payload["access_key_type"] = access_key_type
+
+        self._request("POST", "vapp/access-key/update", json=payload)
+
+    def add_apps_to_access_keys(self, access_keys: List[str], app_ids: List[str]) -> None:
+        """向访问密钥添加应用
+
+        Args:
+            access_keys: 访问密钥列表
+            app_ids: 要添加的应用ID列表
+        """
+        payload = {"access_keys": access_keys, "app_ids": app_ids}
+        self._request("POST", "vapp/access-key/add-apps", json=payload)
+
+    def remove_apps_from_access_keys(self, access_keys: List[str], app_ids: List[str]) -> None:
+        """从访问密钥移除应用
+
+        Args:
+            access_keys: 访问密钥列表
+            app_ids: 要移除的应用ID列表
+        """
+        payload = {"access_keys": access_keys, "app_ids": app_ids}
+        self._request("POST", "vapp/access-key/remove-apps", json=payload)
+
+    def generate_vapp_url(
+        self,
+        app_id: str,
+        access_key: str,
+        key_id: str,
+        timeout: int = 15 * 60,
+        base_url: str = "https://vectorvein.com",
+    ) -> str:
+        """生成VApp访问链接
+
+        Args:
+            app_id: VApp ID
+            access_key: 访问密钥
+            key_id: 密钥ID
+            timeout: 超时时间（秒）
+            base_url: 基础URL
+
+        Returns:
+            str: VApp访问链接
+        """
+        timestamp = int(time.time())
+        message = f"{app_id}:{access_key}:{timestamp}:{timeout}"
+        encryption_key = self.api_key.encode()
+
+        cipher = AES.new(encryption_key, AES.MODE_CBC)
+        padded_data = pad(message.encode(), AES.block_size)
+        encrypted_data = cipher.encrypt(padded_data)
+        final_data = bytes(cipher.iv) + encrypted_data
+        token = base64.b64encode(final_data).decode("utf-8")
+        quoted_token = quote(token)
+
+        return f"{base_url}/public/v-app/{app_id}?token={quoted_token}&key_id={key_id}"
+
+
+class AsyncVectorVeinClient:
+    """向量脉络 API 异步客户端类"""
+
+    API_VERSION = "20240508"
+    BASE_URL = "https://vectorvein.com/api/v1/open-api"
+
+    def __init__(self, api_key: str, base_url: Optional[str] = None):
+        """初始化异步客户端
+
+        Args:
+            api_key: API密钥
+            base_url: API基础URL，默认为https://vectorvein.com/api/v1/open-api
+
+        Raises:
+            APIKeyError: API密钥为空或格式不正确
+        """
+        if not api_key or not isinstance(api_key, str):
+            raise APIKeyError("API密钥不能为空且必须是字符串类型")
+
+        self.api_key = api_key
+        self.base_url = base_url or self.BASE_URL
+        self._client = httpx.AsyncClient(
+            headers={
+                "VECTORVEIN-API-KEY": api_key,
+                "VECTORVEIN-API-VERSION": self.API_VERSION,
+            }
+        )
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self._client.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """发送异步HTTP请求
+
+        Args:
+            method: HTTP方法
+            endpoint: API端点
+            params: URL参数
+            json: JSON请求体
+            **kwargs: 其他请求参数
+
+        Returns:
+            Dict[str, Any]: API响应
+
+        Raises:
+            RequestError: 请求错误
+            VectorVeinAPIError: API错误
+            APIKeyError: API密钥无效或已过期
+        """
+        url = f"{self.base_url}/{endpoint}"
+        try:
+            response = await self._client.request(method=method, url=url, params=params, json=json, **kwargs)
+            response.raise_for_status()
+            result = response.json()
+
+            if result["status"] in [401, 403]:
+                raise APIKeyError("API密钥无效或已过期")
+            if result["status"] != 200 and result["status"] != 202:
+                raise VectorVeinAPIError(message=result.get("msg", "Unknown error"), status_code=result["status"])
+            return result
+        except httpx.HTTPError as e:
+            raise RequestError(f"Request failed: {str(e)}")
+
+    @overload
+    async def run_workflow(
+        self,
+        wid: str,
+        input_fields: List[WorkflowInputField],
+        output_scope: Literal["all", "output_fields_only"] = "output_fields_only",
+        wait_for_completion: Literal[False] = False,
+        timeout: int = 30,
+    ) -> str: ...
+
+    @overload
+    async def run_workflow(
+        self,
+        wid: str,
+        input_fields: List[WorkflowInputField],
+        output_scope: Literal["all", "output_fields_only"] = "output_fields_only",
+        wait_for_completion: Literal[True] = True,
+        timeout: int = 30,
+    ) -> WorkflowRunResult: ...
+
+    async def run_workflow(
+        self,
+        wid: str,
+        input_fields: List[WorkflowInputField],
+        output_scope: Literal["all", "output_fields_only"] = "output_fields_only",
+        wait_for_completion: bool = False,
+        timeout: int = 30,
+    ) -> Union[str, WorkflowRunResult]:
+        """异步运行工作流
+
+        Args:
+            wid: 工作流ID
+            input_fields: 输入字段列表
+            output_scope: 输出范围，可选值：'all' 或 'output_fields_only'
+            wait_for_completion: 是否等待完成
+            timeout: 超时时间（秒）
+
+        Returns:
+            Union[str, WorkflowRunResult]: 工作流运行ID或运行结果
+
+        Raises:
+            WorkflowError: 工作流运行错误
+            TimeoutError: 超时错误
+        """
+        payload = {
+            "wid": wid,
+            "output_scope": output_scope,
+            "wait_for_completion": wait_for_completion,
+            "input_fields": [
+                {"node_id": field.node_id, "field_name": field.field_name, "value": field.value}
+                for field in input_fields
+            ],
+        }
+
+        result = await self._request("POST", "workflow/run", json=payload)
+
+        if not wait_for_completion:
+            return result["data"]["rid"]
+
+        rid = result.get("rid") or (isinstance(result["data"], dict) and result["data"].get("rid")) or ""
+        start_time = time.time()
+
+        while True:
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Workflow execution timed out after {timeout} seconds")
+
+            status = await self.check_workflow_status(rid)
+            if status["status"] == 200:
+                return WorkflowRunResult(
+                    rid=rid,
+                    status=status["status"],
+                    msg=status["msg"],
+                    data=[WorkflowOutput(**output) for output in status["data"]],
+                )
+            elif status["status"] == 500:
+                raise WorkflowError(f"Workflow execution failed: {status['msg']}")
+
+            await asyncio.sleep(5)
+
+    async def check_workflow_status(self, rid: str) -> Dict:
+        """异步检查工作流运行状态
+
+        Args:
+            rid: 工作流运行记录ID
+
+        Returns:
+            Dict: 工作流状态信息
+        """
+        payload = {"rid": rid}
+        return await self._request("POST", "workflow/check-status", json=payload)
+
+    async def get_access_keys(
+        self, access_keys: Optional[List[str]] = None, get_type: Literal["selected", "all"] = "selected"
+    ) -> List[AccessKey]:
+        """异步获取访问密钥信息
+
+        Args:
+            access_keys: 访问密钥列表
+            get_type: 获取类型，可选值：'selected' 或 'all'
+
+        Returns:
+            List[AccessKey]: 访问密钥信息列表
+
+        Raises:
+            AccessKeyError: 访问密钥不存在或已失效
+        """
+        params = {"get_type": get_type}
+        if access_keys:
+            params["access_keys"] = ",".join(access_keys)
+
+        try:
+            result = await self._request("GET", "vapp/access-key/get", params=params)
+            return [AccessKey(**key) for key in result["data"]]
+        except VectorVeinAPIError as e:
+            if e.status_code == 404:
+                raise AccessKeyError("访问密钥不存在")
+            elif e.status_code == 403:
+                raise AccessKeyError("访问密钥已失效")
+            raise
+
+    async def create_access_keys(
+        self,
+        access_key_type: Literal["O", "M", "L"],
+        app_id: Optional[str] = None,
+        app_ids: Optional[List[str]] = None,
+        count: int = 1,
+        expire_time: Optional[str] = None,
+        max_credits: Optional[int] = None,
+        max_use_count: Optional[int] = None,
+        description: Optional[str] = None,
+    ) -> List[AccessKey]:
+        """异步创建访问密钥
+
+        Args:
+            access_key_type: 密钥类型，可选值：'O'(一次性)、'M'(多次)、'L'(长期)
+            app_id: 单个应用ID
+            app_ids: 多个应用ID列表
+            count: 创建数量
+            expire_time: 过期时间
+            max_credits: 最大积分限制
+            max_use_count: 最大使用次数
+            description: 描述信息
+
+        Returns:
+            List[AccessKey]: 创建的访问密钥列表
+
+        Raises:
+            AccessKeyError: 创建访问密钥失败，如类型无效、应用不存在等
+        """
+        if access_key_type not in ["O", "M", "L"]:
+            raise AccessKeyError("无效的访问密钥类型，必须是 'O'(一次性)、'M'(多次) 或 'L'(长期)")
+
+        if app_id and app_ids:
+            raise AccessKeyError("不能同时指定 app_id 和 app_ids")
+
+        payload = {"access_key_type": access_key_type, "count": count}
+
+        if app_id:
+            payload["app_id"] = app_id
+        if app_ids:
+            payload["app_ids"] = app_ids
+        if expire_time:
+            payload["expire_time"] = expire_time
+        if max_credits is not None:
+            payload["max_credits"] = max_credits
+        if max_use_count is not None:
+            payload["max_use_count"] = max_use_count
+        if description:
+            payload["description"] = description
+
+        try:
+            result = await self._request("POST", "vapp/access-key/create", json=payload)
+            return [AccessKey(**key) for key in result["data"]]
+        except VectorVeinAPIError as e:
+            if e.status_code == 404:
+                raise AccessKeyError("指定的应用不存在")
+            elif e.status_code == 403:
+                raise AccessKeyError("没有权限创建访问密钥")
+            raise
+
+    async def list_access_keys(
+        self,
+        page: int = 1,
+        page_size: int = 10,
+        sort_field: str = "create_time",
+        sort_order: str = "descend",
+        app_id: Optional[str] = None,
+        status: Optional[List[str]] = None,
+        access_key_type: Optional[Literal["O", "M", "L"]] = None,
+    ) -> AccessKeyListResponse:
+        """异步列出访问密钥
+
+        Args:
+            page: 页码
+            page_size: 每页数量
+            sort_field: 排序字段
+            sort_order: 排序顺序
+            app_id: 应用ID
+            status: 状态列表
+            access_key_type: 密钥类型列表，可选值：'O'(一次性)、'M'(多次)、'L'(长期)
+
+        Returns:
+            AccessKeyListResponse: 访问密钥列表响应
+        """
+        payload = {"page": page, "page_size": page_size, "sort_field": sort_field, "sort_order": sort_order}
+
+        if app_id:
+            payload["app_id"] = app_id
+        if status:
+            payload["status"] = status
+        if access_key_type:
+            payload["access_key_type"] = access_key_type
+
+        result = await self._request("POST", "vapp/access-key/list", json=payload)
+        return AccessKeyListResponse(**result["data"])
+
+    async def delete_access_keys(self, app_id: str, access_keys: List[str]) -> None:
+        """异步删除访问密钥
+
+        Args:
+            app_id: 应用ID
+            access_keys: 要删除的访问密钥列表
+        """
+        payload = {"app_id": app_id, "access_keys": access_keys}
+        await self._request("POST", "vapp/access-key/delete", json=payload)
+
+    async def update_access_keys(
+        self,
+        access_key: Optional[str] = None,
+        access_keys: Optional[List[str]] = None,
+        app_id: Optional[str] = None,
+        app_ids: Optional[List[str]] = None,
+        expire_time: Optional[str] = None,
+        max_use_count: Optional[int] = None,
+        max_credits: Optional[int] = None,
+        description: Optional[str] = None,
+        access_key_type: Optional[Literal["O", "M", "L"]] = None,
+    ) -> None:
+        """异步更新访问密钥
+
+        Args:
+            access_key: 单个访问密钥
+            access_keys: 多个访问密钥列表
+            app_id: 单个应用ID
+            app_ids: 多个应用ID列表
+            expire_time: 过期时间
+            max_use_count: 最大使用次数
+            max_credits: 最大积分限制
+            description: 描述信息
+            access_key_type: 密钥类型，可选值：'O'(一次性)、'M'(多次)、'L'(长期)
+        """
+        payload = {}
+        if access_key:
+            payload["access_key"] = access_key
+        if access_keys:
+            payload["access_keys"] = access_keys
+        if app_id:
+            payload["app_id"] = app_id
+        if app_ids:
+            payload["app_ids"] = app_ids
+        if expire_time:
+            payload["expire_time"] = expire_time
+        if max_use_count is not None:
+            payload["max_use_count"] = max_use_count
+        if max_credits is not None:
+            payload["max_credits"] = max_credits
+        if description:
+            payload["description"] = description
+        if access_key_type:
+            payload["access_key_type"] = access_key_type
+
+        await self._request("POST", "vapp/access-key/update", json=payload)
+
+    async def add_apps_to_access_keys(self, access_keys: List[str], app_ids: List[str]) -> None:
+        """异步向访问密钥添加应用
+
+        Args:
+            access_keys: 访问密钥列表
+            app_ids: 要添加的应用ID列表
+        """
+        payload = {"access_keys": access_keys, "app_ids": app_ids}
+        await self._request("POST", "vapp/access-key/add-apps", json=payload)
+
+    async def remove_apps_from_access_keys(self, access_keys: List[str], app_ids: List[str]) -> None:
+        """异步从访问密钥移除应用
+
+        Args:
+            access_keys: 访问密钥列表
+            app_ids: 要移除的应用ID列表
+        """
+        payload = {"access_keys": access_keys, "app_ids": app_ids}
+        await self._request("POST", "vapp/access-key/remove-apps", json=payload)
+
+    async def generate_vapp_url(
+        self,
+        app_id: str,
+        access_key: str,
+        key_id: str,
+        timeout: int = 15 * 60,
+        base_url: str = "https://vectorvein.com",
+    ) -> str:
+        """异步生成VApp访问链接
+
+        Args:
+            app_id: VApp ID
+            access_key: 访问密钥
+            key_id: 密钥ID
+            timeout: 超时时间（秒）
+            base_url: 基础URL
+
+        Returns:
+            str: VApp访问链接
+        """
+        timestamp = int(time.time())
+        message = f"{app_id}:{access_key}:{timestamp}:{timeout}"
+        encryption_key = self.api_key.encode()
+
+        cipher = AES.new(encryption_key, AES.MODE_CBC)
+        padded_data = pad(message.encode(), AES.block_size)
+        encrypted_data = cipher.encrypt(padded_data)
+        final_data = bytes(cipher.iv) + encrypted_data
+        token = base64.b64encode(final_data).decode("utf-8")
+        quoted_token = quote(token)
+
+        return f"{base_url}/public/v-app/{app_id}?token={quoted_token}&key_id={key_id}"

vectorvein/api/exceptions.py

@@ -0,0 +1,41 @@
+"""向量脉络 API 异常类定义"""
+
+from typing import Optional
+
+
+class VectorVeinAPIError(Exception):
+    """向量脉络 API 基础异常类"""
+
+    def __init__(self, message: str, status_code: Optional[int] = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class APIKeyError(VectorVeinAPIError):
+    """API密钥相关错误"""
+
+    pass
+
+
+class WorkflowError(VectorVeinAPIError):
+    """工作流相关错误"""
+
+    pass
+
+
+class AccessKeyError(VectorVeinAPIError):
+    """访问密钥相关错误"""
+
+    pass
+
+
+class RequestError(VectorVeinAPIError):
+    """请求相关错误"""
+
+    pass
+
+
+class TimeoutError(VectorVeinAPIError):
+    """超时错误"""
+
+    pass

vectorvein/api/models.py

@@ -0,0 +1,74 @@
+"""向量脉络 API 数据模型定义"""
+
+from dataclasses import dataclass
+from typing import List, Dict, Optional, Any
+
+
+@dataclass
+class VApp:
+    """VApp 信息"""
+
+    app_id: str
+    title: str
+    description: str
+    info: Dict[str, Any]
+    images: List[str]
+
+
+@dataclass
+class AccessKey:
+    """访问密钥信息"""
+
+    access_key: str
+    access_key_type: str  # O: 一次性, M: 多次, L: 长期
+    use_count: int
+    max_use_count: Optional[int]
+    max_credits: Optional[int]
+    used_credits: int
+    v_app: Optional[VApp]
+    v_apps: List[VApp]
+    records: List[Any]
+    status: str  # AC: 有效, IN: 无效, EX: 已过期, US: 已使用
+    access_scope: str  # S: 单应用, M: 多应用
+    description: str
+    create_time: str
+    expire_time: str
+    last_use_time: Optional[str]
+
+
+@dataclass
+class WorkflowInputField:
+    """工作流输入字段"""
+
+    node_id: str
+    field_name: str
+    value: Any
+
+
+@dataclass
+class WorkflowOutput:
+    """工作流输出结果"""
+
+    type: str
+    title: str
+    value: Any
+
+
+@dataclass
+class WorkflowRunResult:
+    """工作流运行结果"""
+
+    rid: str
+    status: int
+    msg: str
+    data: List[WorkflowOutput]
+
+
+@dataclass
+class AccessKeyListResponse:
+    """访问密钥列表响应"""
+
+    access_keys: List[AccessKey]
+    total: int
+    page_size: int
+    page: int

vectorvein-0.2.1.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.1
+Name: vectorvein
+Version: 0.2.1
+Summary: VectorVein python SDK
+Author-Email: Anderson <andersonby@163.com>
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: openai>=1.37.1
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: anthropic[bedrock,vertex]>=0.31.2
+Requires-Dist: pydantic>=2.8.2
+Requires-Dist: Pillow>=10.4.0
+Requires-Dist: deepseek-tokenizer>=0.1.0
+Requires-Dist: qwen-tokenizer>=0.2.0
+Requires-Dist: google-auth>=2.35.0
+Requires-Dist: pycryptodome>=3.21.0
+Provides-Extra: server
+Requires-Dist: fastapi; extra == "server"
+Requires-Dist: uvicorn; extra == "server"
+Provides-Extra: redis
+Requires-Dist: redis; extra == "redis"
+Provides-Extra: diskcache
+Requires-Dist: diskcache; extra == "diskcache"
+Description-Content-Type: text/markdown
+
+# 向量脉络 API 包
+
+这是一个用于调用向量脉络官方API的Python包装器。它提供了简单易用的接口来访问向量脉络的工作流和VApp功能。
+
+## 安装
+
+```bash
+pip install -r requirements.txt
+```
+
+## 使用示例
+
+### 初始化客户端
+
+```python
+from vectorvein.api import VectorVeinClient
+
+# 创建客户端实例
+client = VectorVeinClient(api_key="YOUR_API_KEY")
+```
+
+### 运行工作流
+
+```python
+from vectorvein.api import WorkflowInputField
+
+# 准备工作流输入字段
+input_fields = [
+    WorkflowInputField(
+        node_id="8fc6eceb-8599-46a7-87fe-58bf7c0b633e",
+        field_name="商品名称",
+        value="测试商品"
+    )
+]
+
+# 异步运行工作流
+rid = client.run_workflow(
+    wid="abcde0985736457aa72cc667f17bfc89",
+    input_fields=input_fields,
+    wait_for_completion=False
+)
+print(f"工作流运行ID: {rid}")
+
+# 同步运行工作流
+result = client.run_workflow(
+    wid="abcde0985736457aa72cc667f17bfc89",
+    input_fields=input_fields,
+    wait_for_completion=True
+)
+print(f"工作流运行结果: {result}")
+```
+
+### 管理访问密钥
+
+```python
+# 创建访问密钥
+keys = client.create_access_keys(
+    access_key_type="L",  # L: 长期, M: 多次, O: 一次性
+    app_id="YOUR_APP_ID",
+    count=1,
+    max_credits=500,
+    description="测试密钥"
+)
+print(f"创建的访问密钥: {keys}")
+
+# 获取访问密钥信息
+keys = client.get_access_keys(["ACCESS_KEY_1", "ACCESS_KEY_2"])
+print(f"访问密钥信息: {keys}")
+
+# 列出访问密钥
+response = client.list_access_keys(
+    page=1,
+    page_size=10,
+    sort_field="create_time",
+    sort_order="descend"
+)
+print(f"访问密钥列表: {response}")
+
+# 更新访问密钥
+client.update_access_keys(
+    access_key="ACCESS_KEY",
+    description="更新的描述"
+)
+
+# 删除访问密钥
+client.delete_access_keys(
+    app_id="YOUR_APP_ID",
+    access_keys=["ACCESS_KEY_1", "ACCESS_KEY_2"]
+)
+```
+
+### 生成VApp访问链接
+
+```python
+url = client.generate_vapp_url(
+    app_id="YOUR_APP_ID",
+    access_key="YOUR_ACCESS_KEY",
+    key_id="YOUR_KEY_ID"
+)
+print(f"VApp访问链接: {url}")
+```
+
+## API文档
+
+### VectorVeinClient
+
+主要的API客户端类，提供以下方法：
+
+- `run_workflow()` - 运行工作流
+- `check_workflow_status()` - 检查工作流运行状态
+- `get_access_keys()` - 获取访问密钥信息
+- `create_access_keys()` - 创建访问密钥
+- `list_access_keys()` - 列出访问密钥
+- `delete_access_keys()` - 删除访问密钥
+- `update_access_keys()` - 更新访问密钥
+- `add_apps_to_access_keys()` - 向访问密钥添加应用
+- `remove_apps_from_access_keys()` - 从访问密钥移除应用
+- `generate_vapp_url()` - 生成VApp访问链接
+
+### 数据模型
+
+- `VApp` - VApp信息
+- `AccessKey` - 访问密钥信息
+- `WorkflowInputField` - 工作流输入字段
+- `WorkflowOutput` - 工作流输出结果
+- `WorkflowRunResult` - 工作流运行结果
+- `AccessKeyListResponse` - 访问密钥列表响应
+
+### 异常类
+
+- `VectorVeinAPIError` - API基础异常类
+- `APIKeyError` - API密钥相关错误
+- `WorkflowError` - 工作流相关错误
+- `AccessKeyError` - 访问密钥相关错误
+- `RequestError` - 请求相关错误
+- `TimeoutError` - 超时错误
+
+## 注意事项
+
+1. 请妥善保管您的API密钥，不要将其泄露给他人。
+2. API调用有速率限制，每分钟最多60次调用。
+3. 建议在生产环境中使用异步方式运行工作流，避免长时间等待。
+4. 访问密钥的类型一旦创建就不能更改，请谨慎选择。
+5. 生成的VApp访问链接有效期默认为15分钟，请及时使用。

{vectorvein-0.1.95.dist-info → vectorvein-0.2.1.dist-info}/RECORD

@@ -1,7 +1,11 @@
-vectorvein-0.1.95.dist-info/METADATA,sha256=9jaFqXZu5L1clFveApXDGA8IQEsC72Q7pyGibiFBAfU,775
-vectorvein-0.1.95.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
-vectorvein-0.1.95.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+vectorvein-0.2.1.dist-info/METADATA,sha256=MuvWxw_gudRvlueGAhNhgl-4rHhMpb2sygCZlqA-tjM,4413
+vectorvein-0.2.1.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
+vectorvein-0.2.1.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
 vectorvein/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vectorvein/api/__init__.py,sha256=lfY-XA46fgD2iIZTU0VYP8i07AwA03Egj4Qua0vUKrQ,738
+vectorvein/api/client.py,sha256=THL2epmILfYk5ZTzWbyeWgkFndlD8NNwDGHK2ammQyE,29110
+vectorvein/api/exceptions.py,sha256=btfeXfNfc7zLykMKklpJePLnmJie5YSxCYHyMReCC9s,751
+vectorvein/api/models.py,sha256=z5MeXMxWFHlNkP5vjVz6gEn5cxD1FbQ8pQvbx9KtgkE,1422
 vectorvein/chat_clients/__init__.py,sha256=omQuG4PRRPNflSAgtdU--rwsWG6vMpwMEyIGZyFVHVQ,18596
 vectorvein/chat_clients/anthropic_client.py,sha256=Zk6X1feIvv7Az5dgyipJXbm9TkgWgpFghSTxLiXKKA8,38405
 vectorvein/chat_clients/baichuan_client.py,sha256=CVMvpgjdrZGv0BWnTOBD-f2ufZ3wq3496wqukumsAr4,526
@@ -55,4 +59,4 @@ vectorvein/workflow/nodes/vector_db.py,sha256=t6I17q6iR3yQreiDHpRrksMdWDPIvgqJs0
 vectorvein/workflow/nodes/video_generation.py,sha256=qmdg-t_idpxq1veukd-jv_ChICMOoInKxprV9Z4Vi2w,4118
 vectorvein/workflow/nodes/web_crawlers.py,sha256=LsqomfXfqrXfHJDO1cl0Ox48f4St7X_SL12DSbAMSOw,5415
 vectorvein/workflow/utils/json_to_code.py,sha256=F7dhDy8kGc8ndOeihGLRLGFGlquoxVlb02ENtxnQ0C8,5914
-vectorvein-0.1.95.dist-info/RECORD,,
+vectorvein-0.2.1.dist-info/RECORD,,

vectorvein-0.1.95.dist-info/METADATA

@@ -1,26 +0,0 @@
-Metadata-Version: 2.1
-Name: vectorvein
-Version: 0.1.95
-Summary: VectorVein python SDK
-Author-Email: Anderson <andersonby@163.com>
-License: MIT
-Requires-Python: >=3.10
-Requires-Dist: openai>=1.37.1
-Requires-Dist: tiktoken>=0.7.0
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: anthropic[bedrock,vertex]>=0.31.2
-Requires-Dist: pydantic>=2.8.2
-Requires-Dist: Pillow>=10.4.0
-Requires-Dist: deepseek-tokenizer>=0.1.0
-Requires-Dist: qwen-tokenizer>=0.2.0
-Requires-Dist: google-auth>=2.35.0
-Provides-Extra: server
-Requires-Dist: fastapi; extra == "server"
-Requires-Dist: uvicorn; extra == "server"
-Provides-Extra: redis
-Requires-Dist: redis; extra == "redis"
-Provides-Extra: diskcache
-Requires-Dist: diskcache; extra == "diskcache"
-Description-Content-Type: text/markdown
-
-# vectorvein