A comprehensive Python SDK for the Venice AI API, providing complete access to all Venice AI services including chat completions, image generation, audio synthesis, character management, and more.
- π¬ Chat Completions - Advanced LLM text generation with streaming
- π§ Models - Complete model management and discovery
- π Embeddings - Vector generation and semantic search
- π Characters - AI persona and character management
- πΌοΈ Image Generation - Create images from text descriptions
- βοΈ Image Editing - Edit existing images with AI
- π Image Upscaling - Enhance image resolution and quality
- π¨ Image Styles - Access to artistic style presets
- π± Data URL Support - Handle base64-encoded images seamlessly
- π Text-to-Speech - Convert text to natural-sounding speech
- π€ Multiple Voices - Choose from various voice options
- π Audio Formats - Support for MP3, WAV, AAC, and more
- π₯ Text-to-Video - Generate videos from text descriptions
- πΌοΈ Image-to-Video - Animate static images into video clips
- π° Price Quotes - Get cost estimates before generation
- β±οΈ Async Processing - Queue jobs and track progress
- π₯ Video Download - Easy video file download and management
- π API Key Management - Create, list, and delete API keys
- π Web3 Integration - Generate Web3-compatible keys
- π Usage Tracking - Monitor API usage and billing
- β‘ Rate Limiting - Built-in rate limit management
- π Admin Features - Full administrative access with admin API keys
- π Streaming - Real-time response streaming with SSE support
- π οΈ Function Calling - Tool and function integration
- π Web Search - Integrated web search capabilities
- π Model Analytics - Advanced model traits and compatibility
- β‘ Error Handling - Comprehensive error handling with retries
- π Type Safety - Full type hints and documentation
- π OpenAI Compatibility - Drop-in replacement for OpenAI SDK
- β Robust Testing - 1069 tests with 100% pass rate
pip install venice-sdkfrom venice_sdk import VeniceClient, create_client
# Initialize the client (loads from VENICE_API_KEY env var)
client = VeniceClient()
# Or create with explicit API key
# client = create_client(api_key="your-api-key")
# Chat completions
response = client.chat.complete(
messages=[
{"role": "user", "content": "Hello! What can you help me with?"}
],
model="llama-3.3-70b",
temperature=0.7,
max_completion_tokens=500
)
print(response.choices[0].message.content)
# Image generation
image = client.images.generate(
prompt="A serene mountain landscape at sunset",
model="dall-e-3"
)
image.save("mountain.png")
# Text-to-speech
audio = client.audio.speech(
input_text="Hello from Venice AI!",
voice="alloy"
)
audio.save("hello.mp3")
# Generate embeddings
embeddings = client.embeddings.generate([
"The quick brown fox jumps over the lazy dog",
"A fast brown fox leaps over a sleepy dog"
])
similarity = embeddings[0].cosine_similarity(embeddings[1])
print(f"Similarity: {similarity}")
# Video generation
job = client.video.queue(
model="kling-2.6-pro-text-to-video",
prompt="A serene sunset over a calm ocean",
duration=5,
aspect_ratio="16:9"
)
completed_job = client.video.wait_for_completion(job.job_id)
if completed_job.is_completed():
completed_job.download("video.mp4")
# List available characters
characters = client.characters.list()
for char in characters[:3]:
print(f"- {char.name}: {char.description}")
# Check account usage
usage = client.billing.get_usage()
print(f"Credits remaining: {usage.credits_remaining}")
# Advanced usage with pagination
from datetime import datetime, timedelta
end_date = datetime.now()
start_date = end_date - timedelta(days=30)
usage = client.billing.get_usage(
currency="USD",
start_date=start_date,
end_date=end_date,
limit=50,
page=1,
sort_order="desc"
)
# Access pagination info
if usage.pagination:
print(f"Page {usage.pagination['page']} of {usage.pagination['totalPages']}")
print(f"Total records: {usage.pagination['total']}")# Generate an image
image = client.images.generate(
prompt="A futuristic cityscape at night",
model="dall-e-3",
size="1024x1024",
quality="hd"
)
# Edit an existing image
edited = client.image_edit.edit(
image="path/to/image.png",
prompt="Add a rainbow in the sky",
model="dall-e-2-edit"
)
# Upscale an image
upscaled = client.image_upscale.upscale(
image="path/to/small_image.png",
scale=2
)
# List available styles
styles = client.image_styles.list_styles()
for style in styles:
print(f"{style.name}: {style.description}")# Convert text to speech
audio = client.audio.speech(
input_text="Hello, this is a test of the Venice AI text-to-speech system.",
voice="alloy",
response_format="mp3",
speed=1.0
)
# Save to file
audio.save("speech.mp3")
# List available voices
voices = client.audio.get_voices()
for voice in voices:
print(f"{voice.name}: {voice.description}")
# Batch processing
from venice_sdk import AudioBatchProcessor
processor = AudioBatchProcessor(client.audio)
texts = ["Hello", "World", "Venice AI"]
saved_files = processor.process_batch(texts, "output_dir/")# List all characters
characters = client.characters.list()
# Search for specific characters
assistants = client.characters.search("assistant")
# Get a specific character
venice_char = client.characters.get("venice")
# Use character in chat
response = client.chat.complete(
messages=[{"role": "user", "content": "Tell me about yourself"}],
model="llama-3.3-70b",
venice_parameters={"character_slug": "venice"}
)# Generate embeddings
embeddings = client.embeddings.generate([
"Machine learning is fascinating",
"AI will change the world",
"The weather is nice today"
])
# Calculate similarity
similarity = embeddings[0].cosine_similarity(embeddings[1])
print(f"Similarity: {similarity}")
# Semantic search
from venice_sdk import SemanticSearch
search = SemanticSearch(client.embeddings)
search.add_documents([
"Python is a programming language",
"Machine learning uses algorithms",
"The sky is blue"
])
results = search.search("programming", top_k=2)
for result in results:
print(f"{result['similarity']:.3f}: {result['document']}")# Text-to-video generation
job = client.video.queue(
model="kling-2.6-pro-text-to-video",
prompt="A cat playing with a ball of yarn in slow motion",
duration=5,
aspect_ratio="16:9",
resolution="1080p"
)
# Wait for completion with progress tracking
def track_progress(job):
print(f"Status: {job.status} - {job.progress}%")
completed_job = client.video.wait_for_completion(
job.job_id,
poll_interval=5,
callback=track_progress
)
if completed_job.is_completed():
completed_job.download("cat_video.mp4")
# Get price quote before generating
quote = client.video.quote(
model="kling-2.6-pro-text-to-video",
prompt="A beautiful sunset",
duration=10,
resolution="1080p"
)
print(f"Estimated cost: ${quote.estimated_cost} {quote.currency}")
# Image-to-video animation
image = client.images.generate(
prompt="A serene mountain landscape",
model="dall-e-3"
)
animated_job = client.video.queue(
model="kling-2.6-pro-image-to-video",
image=image.url,
prompt="Animate with gentle movement",
duration=5
)
completed_animated = client.video.wait_for_completion(animated_job.job_id)
if completed_animated.is_completed():
completed_animated.download("animated_landscape.mp4")# Get account usage
usage = client.billing.get_usage()
print(f"Total usage: {usage.total_usage}")
print(f"Credits remaining: {usage.credits_remaining}")
# Check rate limits
limits = client.api_keys.get_rate_limits()
print(f"Requests per minute: {limits.requests_per_minute}")
# Generate Web3 API key
web3_key = client.api_keys.generate_web3_key(
name="Web3 Integration",
description="For blockchain applications"
)
print(f"Web3 Key: {web3_key.api_key}")
# Get account summary
summary = client.get_account_summary()
print(f"Account Summary: {summary}")# List all API keys
api_keys = client.api_keys.list()
for key in api_keys:
print(f"Key: {key.name} ({key.id})")
print(f" Type: {key.permissions.get('type', 'Unknown')}")
print(f" Created: {key.created_at}")
# Create a new API key
new_key = client.api_keys.create(
name="My New Key",
permissions=["read", "write"]
)
print(f"Created key: {new_key.id}")
# Get specific API key details
key_details = client.api_keys.get(new_key.id)
print(f"Key details: {key_details}")
# Delete an API key
success = client.api_keys.delete(new_key.id)
print(f"Key deleted: {success}")
# Get comprehensive billing information
billing_summary = client.billing.get_billing_summary()
print(f"Billing Summary: {billing_summary}")
# Get detailed usage by model
model_usage = client.billing.get_usage_by_model()
for model, usage in model_usage.items():
print(f"{model}: {usage.requests} requests, {usage.tokens} tokens")# Get model traits
traits = client.models_traits.get_traits()
for model_id, model_traits in traits.items():
print(f"{model_id}:")
print(f" Function calling: {model_traits.supports_function_calling()}")
print(f" Web search: {model_traits.supports_web_search()}")
# Get compatibility mapping
mapping = client.models_compatibility.get_mapping()
venice_model = mapping.get_venice_model("gpt-3.5-turbo")
print(f"OpenAI gpt-3.5-turbo maps to: {venice_model}")
# Find models by capability
function_models = client.models_traits.find_models_by_capability("function_calling")
print(f"Models with function calling: {function_models}")The SDK includes a command-line interface for managing your API credentials:
# Set your API key
venice auth your-api-key-here
# Check authentication status
venice status# Advanced parameter control
response = client.chat.complete(
messages=[{"role": "user", "content": "Write a creative story"}],
model="llama-3.3-70b",
temperature=1.2,
frequency_penalty=0.3,
presence_penalty=-0.1,
repetition_penalty=1.1,
max_completion_tokens=500,
n=3, # Generate 3 different responses
seed=42, # For reproducible results
stop=["END", "STOP"] # Stop sequences
)
# Dynamic temperature scaling
response = client.chat.complete(
messages=[{"role": "user", "content": "Write a poem"}],
model="llama-3.3-70b",
min_temp=0.5,
max_temp=1.5,
logprobs=True,
top_logprobs=3
)# Stream chat responses in real-time
for chunk in client.chat.complete_stream(
messages=[{"role": "user", "content": "Tell me a story about a robot"}],
model="llama-3.3-70b"
):
print(chunk, end="", flush=True)
# Or use the streaming method directly
response = client.chat.complete(
messages=[{"role": "user", "content": "Hello!"}],
model="llama-3.3-70b",
stream=True,
stream_options={"include_usage": True}
)
for chunk in response:
if chunk.get("choices") and chunk["choices"][0].get("delta", {}).get("content"):
print(chunk["choices"][0]["delta"]["content"], end="", flush=True)# Define tools
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather in a location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"]
}
}
}
]
# Use tools in chat
response = chat.complete(
messages=[{"role": "user", "content": "What's the weather in San Francisco?"}],
model="llama-3.3-70b",
tools=tools
)from venice_sdk.errors import VeniceAPIError, RateLimitError, UnauthorizedError
try:
response = chat.complete(...)
except RateLimitError:
print("Rate limit exceeded. Please try again later.")
except UnauthorizedError:
print("Authentication failed. Please check your API key.")
except VeniceAPIError as e:
print(f"API error: {e}")- π Admin API Key Management: Full support for creating, listing, and deleting API keys
- π Enhanced Billing: Comprehensive usage tracking and rate limiting
- π Improved Streaming: Better Server-Sent Events (SSE) support for real-time responses
- πΌοΈ Image Enhancements: Data URL support and improved file handling
- β Robust Testing: 1069 tests with 100% pass rate
- π‘οΈ Better Error Handling: More descriptive error messages and validation
- Fixed all data structure mismatches with the actual Venice AI API
- Updated capability mapping to use correct API names
- Aligned all data classes with real API response formats
- Improved timeout handling and retry logic
- Enhanced test isolation to prevent interference
- Better environment variable management
- Comprehensive input validation
The SDK can be configured in several ways:
-
Environment variables:
export VENICE_API_KEY="your-api-key" export VENICE_BASE_URL="https://api.venice.ai/api/v1"
-
.envfile:VENICE_API_KEY=your-api-key VENICE_BASE_URL=https://api.venice.ai/api/v1
-
Direct initialization:
client = VeniceClient( api_key="your-api-key", base_url="https://api.venice.ai/api/v1" )
- Clone the repository
- Install development dependencies:
pip install -e ".[dev]" - Set up your environment variables in
.env:VENICE_API_KEY=your-api-key-here
- Run tests:
# Run all tests pytest # Run only live tests (requires API key) pytest tests/live/ # Run specific test categories pytest tests/unit/ pytest tests/integration/ pytest tests/e2e/
The SDK includes a comprehensive test suite with:
- 1069 tests covering all functionality
- 100% pass rate with robust error handling
- Live API tests for real-world validation
- Unit tests for isolated component testing
- Integration tests for cross-module functionality
- E2E tests for complete workflow validation
To build the documentation:
pip install -e ".[docs]"
mkdocs serveThis project uses a dual license structure:
- Code/Software: GNU Affero General Public License v3.0 (AGPLv3) - Strong copyleft protection, requires source code availability for network services
- Documentation/Examples: Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA) - Attribution required, derivative works must use same license
The Python SDK code is licensed under AGPLv3, while all documentation and examples are licensed under CC-BY-SA 4.0.
Contributions are welcome! Please feel free to submit a Pull Request.