{"id":46833937,"url":"https://github.com/zai-org/z-ai-sdk-python","last_synced_at":"2026-03-10T11:04:20.631Z","repository":{"id":304092233,"uuid":"1011806705","full_name":"zai-org/z-ai-sdk-python","owner":"zai-org","description":"The official Python SDK for Z.ai's large model open interface, making it easier for developers to call Z.ai's open APIs.","archived":false,"fork":false,"pushed_at":"2026-02-02T16:10:57.000Z","size":1420,"stargazers_count":67,"open_issues_count":5,"forks_count":18,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-02T21:11:16.525Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.z.ai/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zai-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-01T11:15:24.000Z","updated_at":"2026-02-02T16:10:01.000Z","dependencies_parsed_at":"2025-08-04T04:30:18.716Z","dependency_job_id":"acc686bd-c75a-4985-bc22-851e6f23d213","html_url":"https://github.com/zai-org/z-ai-sdk-python","commit_stats":null,"previous_names":["thudm/z-ai-sdk-python","zai-org/z-ai-sdk-python"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/zai-org/z-ai-sdk-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zai-org%2Fz-ai-sdk-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zai-org%2Fz-ai-sdk-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zai-org%2Fz-ai-sdk-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zai-org%2Fz-ai-sdk-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zai-org","download_url":"https://codeload.github.com/zai-org/z-ai-sdk-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zai-org%2Fz-ai-sdk-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30331644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-10T11:04:16.641Z","updated_at":"2026-03-10T11:04:20.622Z","avatar_url":"https://github.com/zai-org.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Z.ai Open Platform Python SDK\n\n[![PyPI version](https://img.shields.io/pypi/v/zai-sdk.svg)](https://pypi.org/project/zai-sdk/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n\n[中文文档](README_CN.md) | English\n\n[Z.ai Open Platform](https://docs.z.ai/) The official Python SDK for Z.ai's large model open interface, making it easier for developers to call Z.ai's open APIs.\n\n## ✨ Core Features\n\n### 🤖 **Chat Completions**\n- **Standard Chat**: Create chat completions with various models including `glm-4.7`\n- **Streaming Support**: Real-time streaming responses for interactive applications\n- **Tool Calling**: Function calling capabilities for enhanced AI interactions\n- **Character Role-Playing**: Support for character-based conversations with `charglm-3` model\n- **Multimodal Chat**: Image understanding capabilities with vision models\n\n### 🧠 **Embeddings**\n- **Text Embeddings**: Generate high-quality vector embeddings for text\n- **Configurable Dimensions**: Customizable embedding dimensions\n- **Batch Processing**: Support for multiple inputs in a single request\n\n### 🎥 **Video Generation**\n- **Text-to-Video**: Generate videos from text prompts\n- **Image-to-Video**: Create videos from image inputs\n- **Customizable Parameters**: Control quality, duration, FPS, and size\n- **Audio Support**: Optional audio generation for videos\n\n### 🎵 **Audio Processing**\n- **Speech Transcription**: Convert audio files to text\n- **Multiple Formats**: Support for various audio file formats\n\n### 🤝 **Assistant API**\n- **Conversation Management**: Structured conversation handling\n- **Streaming Conversations**: Real-time assistant interactions\n- **Metadata Support**: Rich conversation context and user information\n\n### 🔧 **Advanced Tools**\n- **Web Search**: Integrated web search capabilities\n- **File Management**: Upload, download, and manage files\n- **Batch Operations**: Efficient batch processing for multiple requests\n- **Content Moderation**: Built-in content safety and moderation\n- **Image Generation**: AI-powered image creation\n\n## 📦 Installation\n\n### Requirements\n\n- **Python**: 3.8+\n- **Package Manager**: pip\n\n### Install via pip\n\n```bash\npip install zai-sdk\n```\n\n### 📋 **Technical Specifications**\n\n#### **Python Support**\n- **Python Versions**: 3.8, 3.9, 3.10, 3.11, 3.12\n- **Async Support**: Full async/await compatibility\n- **Cross-platform**: Windows, macOS, Linux support\n\n#### **Core Dependencies**\n\n| Package | Version | Purpose |\n|---------|---------|----------|\n| `httpx` | `\u003e=0.23.0` | HTTP client for API requests |\n| `pydantic` | `\u003e=1.9.0,\u003c3.0.0` | Data validation and serialization |\n| `typing-extensions` | `\u003e=4.0.0` | Enhanced type hints support |\n| `cachetools` | `\u003e=4.2.2` | Caching utilities |\n| `pyjwt` | `\u003e=2.8.0` | JSON Web Token (JWT) handling |\n\n## 🚀 Quick Start\n\n### Create API Key\n\n#### Get API Key\n- **Overseas regions**: Visit [Z.ai Open Platform](https://docs.z.ai/) to get your API key\n- **Mainland China regions**: Visit [Zhipu AI Open Platform](https://www.bigmodel.cn/) to get your API key\n\n#### API BASE URL\n- **Mainland China regions**: `https://open.bigmodel.cn/api/paas/v4/`\n- **Overseas regions**: `https://api.z.ai/api/paas/v4/`\n\n#### Usage Steps\n1. **Create client with API key**\n2. **Call the corresponding API methods**\n\nFor complete examples, please refer to the open platform [API Reference](https://docs.z.ai/api-reference/) and [User Guide](https://docs.z.ai/guides/), and remember to replace with your own API key.\n\n### Basic Usage\n\n```python\nfrom zai import ZaiClient, ZhipuAiClient\n\n# For Overseas users, create the ZaiClient\nclient = ZaiClient(api_key=\"your-api-key\")\n\n# For Chinese users, create the ZhipuAiClient\nclient = ZhipuAiClient(api_key=\"your-api-key\")\n\n# Create chat completion\nresponse = client.chat.completions.create(\n    model=\"glm-5\",\n    messages=[\n        {\"role\": \"user\", \"content\": \"Hello, Z.ai!\"}\n    ]\n)\nprint(response.choices[0].message.content)\n```\n\n### Client Configuration\n\nThe SDK supports multiple ways to configure API keys:\n\n#### Environment Variables\n\n```bash\nexport ZAI_API_KEY=\"your-api-key\"\nexport ZAI_BASE_URL=\"https://api.z.ai/api/paas/v4/\"  # Optional\n```\n\n#### Code Configuration\n\n```python\nfrom zai import ZaiClient, ZhipuAiClient\n\nclient = ZaiClient(\n    api_key=\"your-api-key\",\n    base_url=\"https://api.z.ai/api/paas/v4/\"  # Optional\n)\n\n# if you want to use Zhipu's domain service\nzhipu_client = ZhipuAiClient(\n    api_key=\"your-api-key\",\n    base_url=\"https://open.bigmodel.cn/api/paas/v4/\"  # Optional\n)\n```\n\n### Advanced Configuration\n\nCustomize client behavior with additional parameters:\n\n```python\nfrom zai import ZaiClient\nimport httpx\n\nclient = ZaiClient(\n    api_key=\"your-api-key\",\n    timeout=httpx.Timeout(timeout=300.0, connect=8.0),  # Request timeout\n    max_retries=3,  # Retry attempts\n    base_url=\"https://api.z.ai/api/paas/v4/\"  # Custom API endpoint\n)\n```\n\n## 📖 Usage Examples\n\n### Streaming Chat\n\n```python\nfrom zai import ZaiClient\n\n# Initialize client\nclient = ZaiClient(api_key=\"your-api-key\")\n\n# Create chat completion\nresponse = client.chat.completions.create(\n    model='glm-4.7',\n    messages=[\n        {'role': 'system', 'content': 'You are a helpful assistant.'},\n        {'role': 'user', 'content': 'Tell me a story about AI.'},\n    ],\n    stream=True,\n)\n\nfor chunk in response:\n    if chunk.choices[0].delta.content:\n        print(chunk.choices[0].delta.content, end='')\n```\n\n### Chat With Tool Call\n\n```python\nfrom zai import ZaiClient\n\n# Initialize client\nclient = ZaiClient(api_key=\"your-api-key\")\n\n# Create chat completion\nresponse = client.chat.completions.create(\n    model='glm-4.7',\n    messages=[\n        {'role': 'system', 'content': 'You are a helpful assistant.'},\n        {'role': 'user', 'content': 'What is artificial intelligence?'},\n    ],\n    tools=[\n        {\n            'type': 'web_search',\n            'web_search': {\n                'search_query': 'What is artificial intelligence?',\n                'search_result': True,\n            },\n        }\n    ],\n    temperature=0.5,\n    max_tokens=2000,\n)\n\nprint(response)\n```\n\n### Multimodal Chat\n\n```python\nfrom zai import ZaiClient\nimport base64\n\ndef encode_image(image_path):\n    \"\"\"Encode image to base64 format\"\"\"\n    with open(image_path, 'rb') as image_file:\n        return base64.b64encode(image_file.read()).decode('utf-8')\n\nclient = ZaiClient(api_key=\"your-api-key\")\nbase64_image = encode_image('examples/test_multi_modal.jpeg')\n\nresponse = client.chat.completions.create(\n    model='glm-4.6v',\n    messages=[\n        {\n            'role': 'user',\n            'content': [\n                {'type': 'text', 'text': \"What's in this image?\"},\n                {'type': 'image_url', 'image_url': {'url': f'data:image/jpeg;base64,{base64_image}'}},\n            ],\n        }\n    ],\n    temperature=0.5,\n    max_tokens=2000,\n)\nprint(response)\n```\n\n### Video Generation\n\n```python\nfrom zai import ZaiClient\nclient = ZaiClient(api_key=\"your-api-key\")\n\n# Generate video\nresponse = client.videos.generations(\n    model=\"cogvideox-3\",\n    prompt=\"A cat is playing with a ball.\",\n    quality=\"quality\",  # Output mode, \"quality\" for quality priority, \"speed\" for speed priority\n    with_audio=True, # Whether to include audio\n    size=\"1920x1080\",  # Video resolution, supports up to 4K (e.g., \"3840x2160\")\n    fps=30,  # Frame rate, can be 30 or 60\n    max_wait_time=300,  # Maximum wait time (seconds)\n)\nprint(response)\n\n# Get video result\nresult = client.videos.retrieve_videos_result(id=response.id)\nprint(result)\n```\n\n## 🚨 Error Handling\n\nThe SDK provides comprehensive error handling:\n\n```python\nfrom zai import ZaiClient\nimport zai\n\nclient = ZaiClient(api_key=\"your-api-key\")\n\ntry:\n    response = client.chat.completions.create(\n        model=\"glm-5\",\n        messages=[\n            {\"role\": \"user\", \"content\": \"Hello, Z.ai!\"}\n        ]\n    )\n    print(response.choices[0].message.content)\n    \nexcept zai.core.APIStatusError as err:\n    print(f\"API Status Error: {err}\")\nexcept zai.core.APITimeoutError as err:\n    print(f\"Request Timeout: {err}\")\nexcept Exception as err:\n    print(f\"Unexpected Error: {err}\")\n```\n\n### Error Codes\n\n| Status Code | Error Type | Description |\n|-------------|------------|-------------|\n| 400 | `APIRequestFailedError` | Invalid request parameters |\n| 401 | `APIAuthenticationError` | Authentication failed |\n| 429 | `APIReachLimitError` | Rate limit exceeded |\n| 500 | `APIInternalError` | Internal server error |\n| 503 | `APIServerFlowExceedError` | Server overloaded |\n| N/A | `APIStatusError` | General API error |\n\n## 📈 Version Updates\n\nFor detailed version history and update information, please see [Release-Note.md](Release-Note.md).\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 📞 Support\n\nFor questions and technical support, please visit [Z.ai Open Platform](https://docs.z.ai/) or check our documentation.\n\n### Contact Us\n\nFor feedback and support, please contact us at: **user_feedback@z.ai**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzai-org%2Fz-ai-sdk-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzai-org%2Fz-ai-sdk-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzai-org%2Fz-ai-sdk-python/lists"}