Venice AI Python Client v1.3.0

What's Changed

🚨 Enhanced Exception Handling

• New exception classes for better error handling:
  • PaymentRequiredError (HTTP 402) - Raised when payment is required to access the service
  • ServiceUnavailableError (HTTP 503) - Raised when the service is temporarily unavailable
• Improved error mapping for more specific exception types

🔧 Embeddings API Enhancements

• Input validation with maximum array length (2048 items limit)
• Base64 encoding support with encoding_format parameter ("float" or "base64")
• OpenAI compatibility improvements with user parameter support

🎯 Model Capabilities Expansion

• New model capabilities:
  • supportsVision - Indicates if model supports image inputs
  • supportsReasoning - Indicates if model has reasoning capabilities
  • quantization - Specifies model quantization type
• Beta field support for identifying beta models
• Enhanced model filtering with capability-based parameters

📚 Documentation & Testing

• New test suite with 28 tests for embeddings API alignment
• Updated 13+ test files for new exception handling and model capabilities
• Enhanced E2E tests for new model fields

🐛 Fixes

• Improved client-side robustness in stream handling
• Enhanced pricing information retrieval and cost calculations
• Various test corrections for new exception types

Full Changelog: v1.2.0...v1.3.0

Venice AI Python SDK v1.2.0

🎉 Venice AI Python SDK v1.2.0

Major Features

💰 Cost Management & Estimation

• New venice_ai.costs module for calculating and estimating API usage costs
• Support for both USD and VCU (Venice Compute Units)
• get_model_pricing() method to fetch model pricing information

🧠 Enhanced Chat Completions

• Web search integration with citation support
• Reasoning/thinking controls for supported models
• Advanced sampling parameters (logit_bias, parallel_tool_calls, dynamic temperature)

📦 Dependency Optimization

• tiktoken is now optional (install with pip install venice-ai[tokenizers])
• Moved heavy dependencies to dev-only, resulting in a leaner production package

Breaking Changes

• Model type structure refactored (metadata consolidated under model_spec)
• Chat responses now use Pydantic models instead of TypedDict

Other Improvements

• Project status upgraded to Production/Stable
• Complete test suite overhaul
• Enhanced type safety throughout

See the CHANGELOG for complete details.

Installation

# Lean install (recommended)
pip install venice-ai==1.2.0

# With token counting
pip install venice-ai[tokenizers]==1.2.0

v1.1.2 - Venice Large 128k Context Documentation Update

Documentation Updates for Venice Large 128k Context Window

This release updates the SDK documentation to reflect recent Venice.ai API improvements, specifically the Venice Large model's increased context window from 32k to 128k tokens.

📚 Documentation Changes

• Enhanced README.md: Added Venice Large model examples and context window guidance
• Updated Client Utilities: Added model capability notes and token management best practices
• Enhanced Streaming Guide: Added large context window usage examples
• Comprehensive Examples: Practical demonstrations of leveraging 128k context with max_completion_tokens

🔄 API Compatibility

• No Breaking Changes: Full backward compatibility maintained
• Automatic Benefits: Existing functionality automatically benefits from API improvements
• Venice Large Support: Users can now leverage up to 128k tokens through existing max_completion_tokens parameter
• Cleaner Responses: Non-streaming chat completions now receive improved responses due to server-side processing enhancements

🚀 What's New

• Venice Large model now supports 128k token context window (increased from 32k)
• Server-side "thinking" message processing improvements for cleaner non-streaming responses
• Enhanced documentation with practical examples and best practices

No SDK code changes were required - the existing functionality seamlessly supports these API improvements.

v1.1.1 - Documentation & Test Runner Fixes

Fixed

• Documentation Build Issues: Fixed empty sections in Sphinx API reference documentation that were appearing in Read the Docs builds
  • Updated .readthedocs.yaml to properly install the venice_ai package during documentation builds
  • Added missing imports in src/venice_ai/resources/__init__.py for ApiKeys, AsyncApiKeys, Audio, AsyncAudio, Billing, AsyncBilling, Embeddings, AsyncEmbeddings, and AsyncModels
  • Added comprehensive type imports in src/venice_ai/types/__init__.py for image, api_keys, audio, embeddings, and billing modules
  • Added explicit __all__ list to src/venice_ai/exceptions.py for better module discovery
  • Fixed missing ModelTraitList and ModelCompatibilityList exports in types package
• Test Runner & Coverage: Refactored test_runner.py to use pytest-cov directly, resolving significant code coverage reporting inaccuracies when running tests in parallel with pytest-xdist.
• Embedding Tests: Updated e2e_tests/test_05_embeddings.py with improved and corrected end-to-end tests for embedding functionalities.
• CI Workflow: Modified .github/workflows/python-publish.yaml to enhance test execution, enabling or optimizing parallel test runs.

This release ensures that the API reference documentation will display complete content and that code coverage is accurately reported.

Release v1.1.0 - Enhanced HTTP client, Audio API, Characters API, and more

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[1.1.0] - 2025-06-09

Added

• Implemented support for logprobs and top_logprobs parameters in Chat Completions API, allowing users to retrieve token likelihoods. Includes E2E tests and documentation updates.

🏗️ Core SDK Architecture & Client Enhancements

• BaseClient Foundation: Introduced BaseClient class providing shared functionality for both sync and async clients, including common initialization logic, retry configuration, and transport setup.
• Advanced HTTP Configuration: Added comprehensive HTTP client configuration options to both VeniceClient and AsyncVeniceClient:
  • Support for custom httpx.Client/httpx.AsyncClient instances
  • Direct configuration of proxy, transport, limits, cert, verify, trust_env, HTTP/1.1, HTTP/2 settings
  • Custom event hooks and default encoding support
  • Follow redirects and max redirects configuration
• Global Timeout Management: Implemented default_timeout parameter for setting global timeout defaults across all API calls, with per-request override capability.
• Automatic Retry System: Integrated httpx-retries library with configurable retry behavior:
  • Configurable max_retries (default: 2)
  • Adjustable retry_backoff_factor (default: 0.1)
  • Customizable retry_status_forcelist (default: [429, 500, 502, 503, 504])
  • Respect for Retry-After headers in rate limit responses
• Sentinel Type System: Added NotGiven sentinel type and NOT_GIVEN constant for distinguishing between None and not-provided parameters.

🎵 Audio API Major Expansion

• Streaming Audio Support: Implemented method overloads for create_speech() supporting both streaming and non-streaming audio generation:
  • stream=False: Returns bytes for immediate audio data
  • stream=True: Returns Iterator[bytes] for streaming audio chunks
• Voice Management System: Added comprehensive get_voices() method with advanced filtering:
  • Filter by model ID, gender (male/female/unknown), and region code
  • Automatic voice metadata parsing from voice IDs
  • Language and accent detection for 15+ supported regions
• Enhanced Voice Metadata: Implemented REGION_LANGUAGE_MAPPING supporting:
  • English variants: American, British, Canadian, Scottish, Welsh, Australian, Indian
  • International languages: German, Spanish, French, Italian, Japanese, Korean, Portuguese, Russian, Mandarin Chinese
• Improved Parameter Handling: Set sensible defaults for audio generation (response_format="mp3", speed=1.0).
• Raw Response Support: Added _request_raw_response() and _arequest_raw_response() methods for handling binary audio content and streaming responses.

👥 Characters API Implementation

• Character Listing: Implemented Characters.list() method with support for extra headers, query parameters, and custom timeouts.
• Enhanced Character Model: Completely redesigned Character Pydantic model with modern fields:
  • Core identification: slug, name, description
  • AI capabilities: system_prompt, user_prompt, vision_enabled
  • Media support: image_url, voice_id
  • Organization: category_tags
  • Timestamps: created_at, updated_at with proper datetime handling
• Simplified Character List: Streamlined CharacterList model for cleaner API responses.

🔧 Enhanced Error Handling & Resilience

• Retry-After Header Parsing: Implemented _parse_retry_after_header() function supporting:
  • Integer seconds format (e.g., "120")
  • HTTP-date format (e.g., "Wed, 21 Oct 2015 07:28:00 GMT")
  • Timezone-aware datetime calculations
  • Server time synchronization using response Date header
• Enhanced RateLimitError: Extended RateLimitError with retry_after_seconds attribute for intelligent retry logic.
• Improved Error Context: Better error message formatting and context preservation across the exception hierarchy.

🧪 Comprehensive Testing Infrastructure

• Massive Test Suites: Added extensive functional test coverage:
  • venice_sdk_async_test.py: 126k lines of async functionality tests
  • venice_sdk_sync_test.py: 49k lines of sync functionality tests
• HTTP Configuration Testing: New tests/test_client_http_config.py for validating advanced HTTP client options.
• Enhanced API Coverage: Expanded test coverage for:
  • Audio streaming and non-streaming modes with various parameters
  • Characters API functionality and error handling
  • Chat completions with tool usage, JSON format, and streaming
  • Image generation with advanced parameters (negative_prompt, seed, format)
  • API key management including Web3 token functionality
  • Retry mechanism behavior and configuration
  • Global timeout functionality across all endpoints

📚 Documentation & Project Infrastructure

• Comprehensive Changelog: Created this detailed changelog following Keep a Changelog format.
• Contributing Guidelines: Added CONTRIBUTING.md with clear issue reporting guidelines.
• Enhanced API Documentation: Updated docs/api.rst with 168 new lines covering:
  • Advanced HTTP client configuration examples
  • Retry mechanism documentation
  • Global timeout usage patterns
• Utility Documentation: Added docs/client_utilities.rst documenting estimate_token_count and validate_chat_messages utilities.
• README Overhaul: Major README.md updates (144 lines changed) including:
  • Advanced HTTP Client Configuration section with three configuration approaches
  • Updated all code examples to include default_timeout parameter
  • Enhanced feature list highlighting automatic retry functionality
  • Improved error handling examples and best practices

Changed

🔄 Client Architecture Improvements

• Inheritance Hierarchy: AsyncVeniceClient now inherits from BaseClient for shared functionality and consistent behavior.
• Request Method Simplification: Removed manual HTTP 503 retry loops from client request methods (_request, _arequest, and related stream/multipart methods) in favor of httpx-retries integration.
• Enhanced Documentation: Significantly expanded docstrings for both sync and async clients with detailed parameter descriptions and usage examples.

📦 Project Configuration & Metadata

• Version Bump: Updated from 1.0.3 to 1.1.0 reflecting significant new features and improvements.
• Dependency Management: Added httpx-retries = "^0.4.0" as a core dependency for retry functionality.
• Enhanced Discoverability: Expanded keywords from 5 to 9 terms: ai, api-client, generative-ai, llm, machine-learning, ml, sdk, venice, venice-ai.
• Refined Classifiers: Updated PyPI classifiers:
  • Removed Python 3.10 support (now requires Python 3.11+)
  • Added "Development Status :: 4 - Beta"
  • Added comprehensive topic classifiers for chat, image generation, speech, text processing
  • Added "Typing :: Typed" classifier for type hint support
• Project URLs: Added "Issue Tracker" and "Changelog" links for better project navigation.
• Test Configuration: Enabled parallel test execution with pytest-xdist (addopts = "-n auto").

🎯 API Method Enhancements

• Characters API: Enhanced Characters.list() with additional parameters for headers, query parameters, body, and timeout customization.
• Audio API: Improved create_speech() with better error handling, streaming support, and parameter validation.
• Consistent Parameter Patterns: Standardized optional parameter handling across all API methods using the new NotGiven sentinel system.

Fixed

🐛 API Functionality Corrections

• API Key Management: Corrected API key delete method to use query parameters instead of request body, aligning with API specification.
• Image Upscale Response Handling: Fixed Image Upscale functional tests to correctly handle bytes response type instead of expecting JSON.
• Audio Error Processing: Improved error handling in audio generation to properly consume response bodies before raising exceptions, preventing connection leaks.

🧪 Testing Reliability

• Embeddings Test Stability: Made Embeddings functional tests robustly skipped due to persistent API authentication issues in test environments, preventing false test failures.
• Response Type Validation: Enhanced test assertions to properly validate response types across different API endpoints.

Removed

🗑️ Cleanup & Simplification

• Legacy Files: Removed development and example files:
  • app.py: 883-line example/demo application
  • dummy_image.png and dummy_image_async.png: Test image files
  • tests/resources/test_billing.py: 79-line billing test file
• Billing API Simplification: Removed export() method (71 lines) that provided CSV bill...

v1.0.3

v1.0.3 with minor fixes and improvements to coverage

v1.0.2

Minor updates to the test suite.

v1.0.1

modified the GitHub Actions workflow

v1.0.0

The first release of the venice-ai pypi package.