# VLOEX Python SDK
Official Python SDK for VLOEX - Turn text into professional videos with AI.
[](https://pypi.org/project/vloex/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
---
## 📦 Installation
```bash
pip install vloex
```
**Requirements:** Python 3.7 or higher
---
## 🚀 Quick Start
### Step 1: Get Your API Key
1. Sign up at [vloex.com](https://vloex.com)
2. Go to **Dashboard** → **API Keys**
3. Click **Create New Key**
4. Copy your key (starts with `vs_live_...`)
### Step 2: Create Your First Video
```python
from vloex import Vloex
# Initialize with your API key
vloex = Vloex('vs_live_your_key_here')
# Create a video
video = vloex.videos.create(
script="Hello! This is my first AI-generated video."
)
print(f"✅ Video created: {video['id']}")
print(f"📊 Status: {video['status']}")
```
### Step 3: Get Your Video
```python
import time
# Wait for video to complete
while True:
status = vloex.videos.retrieve(video['id'])
if status['status'] == 'completed':
print(f"🎉 Video ready: {status['url']}")
break
if status['status'] == 'failed':
print(f"❌ Failed: {status.get('error')}")
break
time.sleep(5) # Check again in 5 seconds
```
**That's it!** Your video is ready to share.
---
## 📖 Usage
### Basic Video Generation
```python
from vloex import Vloex
vloex = Vloex('vs_live_your_key_here')
# Simple text to video
video = vloex.videos.create(
script="We just launched version 2.0 with dark mode!"
)
```
### With Custom Options (Coming Soon)
```python
video = vloex.videos.create(
script="Welcome to our product demo!",
options={
'avatar': 'lily', # Only supported avatar
'voice': 'enthusiastic', # Only supported voice
'background': 'modern_office' # Only supported background
}
)
# More avatars, voices, and backgrounds coming soon!
```
### Using Environment Variables
```python
import os
from vloex import Vloex
# Set environment variable
# export VLOEX_API_KEY='vs_live_...'
vloex = Vloex(os.getenv('VLOEX_API_KEY'))
video = vloex.videos.create(script="...")
```
### With Webhooks (Get Notified When Ready)
```python
video = vloex.videos.create(
script="Your video content here",
webhook_url="https://your-app.com/webhook"
)
# Your code continues immediately
# We'll POST to your webhook when the video is ready
```
### Journey Videos (Product Demos)
Create videos from screenshots or URLs:
**Mode 1: Screenshots with Descriptions (Fastest)**
```python
video = vloex.videos.from_journey(
screenshots=['base64img1...', 'base64img2...'],
descriptions=['Login page', 'Dashboard overview'],
product_context='MyApp Demo'
)
```
**Mode 2: URL + Page Paths (Public Pages)**
```python
video = vloex.videos.from_journey(
product_url='https://myapp.com',
pages=['/', '/features', '/pricing'],
product_context='MyApp Website Tour'
)
```
---
## 📚 API Reference
### `vloex.videos.create()`
Create a new video.
**Parameters:**
- `script` (str, required) - The text script for your video
- `webhook_url` (str, optional) - URL to receive completion notification
- `webhook_secret` (str, optional) - Secret for webhook HMAC signature
- `options` (dict, optional) - Customize avatar, voice, background (coming soon)
- `avatar`: `'lily'` (only supported option)
- `voice`: `'enthusiastic'` (only supported option)
- `background`: `'modern_office'` (only supported option)
**Returns:**
```python
{
'id': 'abc-123-def-456',
'status': 'pending',
'created_at': '2025-01-04T12:00:00Z',
'estimated_completion': '2025-01-04T12:05:00Z'
}
```
### `vloex.videos.retrieve(id)`
Get video status and URL.
**Parameters:**
- `id` (str, required) - Video job ID
**Returns:**
```python
{
'id': 'abc-123-def-456',
'status': 'completed', # or 'pending', 'processing', 'failed'
'url': 'https://...', # Video URL when completed
'duration': 12.5, # Video length in seconds
'created_at': '...',
'updated_at': '...'
}
```
---
## 💡 Examples
### Example 1: Simple Video
```python
from vloex import Vloex
vloex = Vloex('vs_live_your_key_here')
video = vloex.videos.create(
script="Check out our new features!"
)
print(f"Video ID: {video['id']}")
```
### Example 2: GitHub Release Announcement
```python
from vloex import Vloex
import requests
# Fetch latest release
release = requests.get(
'https://api.github.com/repos/vercel/next.js/releases/latest'
).json()
# Create announcement video
vloex = Vloex('vs_live_your_key_here')
video = vloex.videos.create(
script=f"Next.js {release['tag_name']} is here! {release['body'][:200]}"
)
print(f"Release video: {video['id']}")
```
**See more examples:** [examples/](./examples)
---
## ⚠️ Error Handling
```python
from vloex import Vloex, VloexError
vloex = Vloex('vs_live_...')
try:
video = vloex.videos.create(script="Hello!")
except VloexError as e:
if e.status_code == 401:
print("Invalid API key")
elif e.status_code == 429:
print("Rate limit exceeded - wait a moment")
elif e.status_code == 402:
print("Quota exceeded - upgrade your plan")
else:
print(f"Error: {e.message}")
```
**Common Errors:**
| Code | Meaning | What to Do |
|------|---------|------------|
| 401 | Invalid API key | Check your key at vloex.com/dashboard |
| 429 | Too many requests | Wait 60 seconds and try again |
| 402 | Quota exceeded | Upgrade your plan |
| 400 | Bad request | Check your script/parameters |
| 500 | Server error | Retry in a few seconds |
---
## 🔧 Advanced
### Custom Timeout
```python
vloex = Vloex(
api_key='vs_live_...',
timeout=60 # seconds
)
```
### Custom API Endpoint
```python
vloex = Vloex(
api_key='vs_live_...',
base_url='https://custom-api.example.com'
)
```
### Debug Mode
```python
import logging
logging.basicConfig(level=logging.DEBUG)
vloex = Vloex('vs_live_...')
# Prints all API requests
```
---
## 📚 Resources
- **Documentation:** https://docs.vloex.com
- **API Docs:** https://api.vloex.com/docs
- **Examples:** [examples/](./examples)
- **GitHub:** https://github.com/vloex/vloex-python
- **npm Package:** https://pypi.org/project/vloex/
---
## 🆘 Support
- **Email:** support@vloex.com
- **Issues:** https://github.com/vloex/vloex-python/issues
---
## 📄 License
MIT License
Raw data
{
"_id": null,
"home_page": "https://api.vloex.com/docs",
"name": "vloex",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "vloex video generation api ai avatar",
"author": "VLOEX",
"author_email": "sats@vloex.com",
"download_url": "https://files.pythonhosted.org/packages/e7/83/f8b146d445e387e6ed44558afe2c28c43b0fb084ba987d036307ef80b5d9/vloex-0.1.5.tar.gz",
"platform": null,
"description": "# VLOEX Python SDK\n\nOfficial Python SDK for VLOEX - Turn text into professional videos with AI.\n\n[](https://pypi.org/project/vloex/)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\npip install vloex\n```\n\n**Requirements:** Python 3.7 or higher\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Step 1: Get Your API Key\n\n1. Sign up at [vloex.com](https://vloex.com)\n2. Go to **Dashboard** \u2192 **API Keys**\n3. Click **Create New Key**\n4. Copy your key (starts with `vs_live_...`)\n\n### Step 2: Create Your First Video\n\n```python\nfrom vloex import Vloex\n\n# Initialize with your API key\nvloex = Vloex('vs_live_your_key_here')\n\n# Create a video\nvideo = vloex.videos.create(\n script=\"Hello! This is my first AI-generated video.\"\n)\n\nprint(f\"\u2705 Video created: {video['id']}\")\nprint(f\"\ud83d\udcca Status: {video['status']}\")\n```\n\n### Step 3: Get Your Video\n\n```python\nimport time\n\n# Wait for video to complete\nwhile True:\n status = vloex.videos.retrieve(video['id'])\n\n if status['status'] == 'completed':\n print(f\"\ud83c\udf89 Video ready: {status['url']}\")\n break\n\n if status['status'] == 'failed':\n print(f\"\u274c Failed: {status.get('error')}\")\n break\n\n time.sleep(5) # Check again in 5 seconds\n```\n\n**That's it!** Your video is ready to share.\n\n---\n\n## \ud83d\udcd6 Usage\n\n### Basic Video Generation\n\n```python\nfrom vloex import Vloex\n\nvloex = Vloex('vs_live_your_key_here')\n\n# Simple text to video\nvideo = vloex.videos.create(\n script=\"We just launched version 2.0 with dark mode!\"\n)\n```\n\n### With Custom Options (Coming Soon)\n\n```python\nvideo = vloex.videos.create(\n script=\"Welcome to our product demo!\",\n options={\n 'avatar': 'lily', # Only supported avatar\n 'voice': 'enthusiastic', # Only supported voice\n 'background': 'modern_office' # Only supported background\n }\n)\n\n# More avatars, voices, and backgrounds coming soon!\n```\n\n### Using Environment Variables\n\n```python\nimport os\nfrom vloex import Vloex\n\n# Set environment variable\n# export VLOEX_API_KEY='vs_live_...'\n\nvloex = Vloex(os.getenv('VLOEX_API_KEY'))\nvideo = vloex.videos.create(script=\"...\")\n```\n\n### With Webhooks (Get Notified When Ready)\n\n```python\nvideo = vloex.videos.create(\n script=\"Your video content here\",\n webhook_url=\"https://your-app.com/webhook\"\n)\n\n# Your code continues immediately\n# We'll POST to your webhook when the video is ready\n```\n\n### Journey Videos (Product Demos)\n\nCreate videos from screenshots or URLs:\n\n**Mode 1: Screenshots with Descriptions (Fastest)**\n```python\nvideo = vloex.videos.from_journey(\n screenshots=['base64img1...', 'base64img2...'],\n descriptions=['Login page', 'Dashboard overview'],\n product_context='MyApp Demo'\n)\n```\n\n**Mode 2: URL + Page Paths (Public Pages)**\n```python\nvideo = vloex.videos.from_journey(\n product_url='https://myapp.com',\n pages=['/', '/features', '/pricing'],\n product_context='MyApp Website Tour'\n)\n```\n\n---\n\n## \ud83d\udcda API Reference\n\n### `vloex.videos.create()`\n\nCreate a new video.\n\n**Parameters:**\n- `script` (str, required) - The text script for your video\n- `webhook_url` (str, optional) - URL to receive completion notification\n- `webhook_secret` (str, optional) - Secret for webhook HMAC signature\n- `options` (dict, optional) - Customize avatar, voice, background (coming soon)\n - `avatar`: `'lily'` (only supported option)\n - `voice`: `'enthusiastic'` (only supported option)\n - `background`: `'modern_office'` (only supported option)\n\n**Returns:**\n```python\n{\n 'id': 'abc-123-def-456',\n 'status': 'pending',\n 'created_at': '2025-01-04T12:00:00Z',\n 'estimated_completion': '2025-01-04T12:05:00Z'\n}\n```\n\n### `vloex.videos.retrieve(id)`\n\nGet video status and URL.\n\n**Parameters:**\n- `id` (str, required) - Video job ID\n\n**Returns:**\n```python\n{\n 'id': 'abc-123-def-456',\n 'status': 'completed', # or 'pending', 'processing', 'failed'\n 'url': 'https://...', # Video URL when completed\n 'duration': 12.5, # Video length in seconds\n 'created_at': '...',\n 'updated_at': '...'\n}\n```\n\n---\n\n## \ud83d\udca1 Examples\n\n### Example 1: Simple Video\n\n```python\nfrom vloex import Vloex\n\nvloex = Vloex('vs_live_your_key_here')\n\nvideo = vloex.videos.create(\n script=\"Check out our new features!\"\n)\n\nprint(f\"Video ID: {video['id']}\")\n```\n\n### Example 2: GitHub Release Announcement\n\n```python\nfrom vloex import Vloex\nimport requests\n\n# Fetch latest release\nrelease = requests.get(\n 'https://api.github.com/repos/vercel/next.js/releases/latest'\n).json()\n\n# Create announcement video\nvloex = Vloex('vs_live_your_key_here')\n\nvideo = vloex.videos.create(\n script=f\"Next.js {release['tag_name']} is here! {release['body'][:200]}\"\n)\n\nprint(f\"Release video: {video['id']}\")\n```\n\n**See more examples:** [examples/](./examples)\n\n---\n\n## \u26a0\ufe0f Error Handling\n\n```python\nfrom vloex import Vloex, VloexError\n\nvloex = Vloex('vs_live_...')\n\ntry:\n video = vloex.videos.create(script=\"Hello!\")\n\nexcept VloexError as e:\n if e.status_code == 401:\n print(\"Invalid API key\")\n elif e.status_code == 429:\n print(\"Rate limit exceeded - wait a moment\")\n elif e.status_code == 402:\n print(\"Quota exceeded - upgrade your plan\")\n else:\n print(f\"Error: {e.message}\")\n```\n\n**Common Errors:**\n\n| Code | Meaning | What to Do |\n|------|---------|------------|\n| 401 | Invalid API key | Check your key at vloex.com/dashboard |\n| 429 | Too many requests | Wait 60 seconds and try again |\n| 402 | Quota exceeded | Upgrade your plan |\n| 400 | Bad request | Check your script/parameters |\n| 500 | Server error | Retry in a few seconds |\n\n---\n\n## \ud83d\udd27 Advanced\n\n### Custom Timeout\n\n```python\nvloex = Vloex(\n api_key='vs_live_...',\n timeout=60 # seconds\n)\n```\n\n### Custom API Endpoint\n\n```python\nvloex = Vloex(\n api_key='vs_live_...',\n base_url='https://custom-api.example.com'\n)\n```\n\n### Debug Mode\n\n```python\nimport logging\n\nlogging.basicConfig(level=logging.DEBUG)\nvloex = Vloex('vs_live_...')\n# Prints all API requests\n```\n\n---\n\n## \ud83d\udcda Resources\n\n- **Documentation:** https://docs.vloex.com\n- **API Docs:** https://api.vloex.com/docs\n- **Examples:** [examples/](./examples)\n- **GitHub:** https://github.com/vloex/vloex-python\n- **npm Package:** https://pypi.org/project/vloex/\n\n---\n\n## \ud83c\udd98 Support\n\n- **Email:** support@vloex.com\n- **Issues:** https://github.com/vloex/vloex-python/issues\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License\n",
"bugtrack_url": null,
"license": null,
"summary": "VLOEX SDK - Video generation as a computing primitive",
"version": "0.1.5",
"project_urls": {
"Bug Reports": "https://github.com/vloex/vloex-python/issues",
"Documentation": "https://api.vloex.com/docs",
"Homepage": "https://api.vloex.com/docs",
"Source": "https://github.com/vloex/vloex-python"
},
"split_keywords": [
"vloex",
"video",
"generation",
"api",
"ai",
"avatar"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2365f2324e7e1f4fecb92aa05625c776fcd1a0e18aeff2cec2abb40008e1f4bc",
"md5": "84097c6359842fe26863c81b0efb201f",
"sha256": "437445775def3d548724eda15b656a2600a1b4c76994e30066d1ca888f38a1c3"
},
"downloads": -1,
"filename": "vloex-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "84097c6359842fe26863c81b0efb201f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7257,
"upload_time": "2025-10-16T22:12:17",
"upload_time_iso_8601": "2025-10-16T22:12:17.426815Z",
"url": "https://files.pythonhosted.org/packages/23/65/f2324e7e1f4fecb92aa05625c776fcd1a0e18aeff2cec2abb40008e1f4bc/vloex-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e783f8b146d445e387e6ed44558afe2c28c43b0fb084ba987d036307ef80b5d9",
"md5": "2b03ed5c272891fb1577eb9c1cfad9a6",
"sha256": "06ec9aa04057085d72c486f5ddd523177ab8483fec7df4d4d03d7666d86fb3b2"
},
"downloads": -1,
"filename": "vloex-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "2b03ed5c272891fb1577eb9c1cfad9a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6884,
"upload_time": "2025-10-16T22:12:18",
"upload_time_iso_8601": "2025-10-16T22:12:18.375032Z",
"url": "https://files.pythonhosted.org/packages/e7/83/f8b146d445e387e6ed44558afe2c28c43b0fb084ba987d036307ef80b5d9/vloex-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-16 22:12:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vloex",
"github_project": "vloex-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "vloex"
}
JSON
