v2.2.0 — the package is now venice-py

The package is now venice-py

pip install venice-py

Your code does not change. The import package is still venice_ai, and VENICE_API_KEY is still VENICE_API_KEY:

from venice_ai import VeniceClient   # unchanged

A distribution name that differs from its import name is ordinary in Python — pillow imports as PIL, python-dotenv as dotenv. Renaming the import package would have broken every existing import venice_ai for no benefit, so it was left alone.

v2.1.0 renamed the CLI binary for the same reason this release renames the package: Venice's official tooling already owns the venice name, and a community SDK sitting on venice-ai invites people to mistake it for an official release.

Upgrading

Update the dependency wherever it is pinned — requirements.txt, pyproject.toml, lockfiles, Dockerfiles, CI installs. Extras are unaffected apart from the name: pip install 'venice-py[cli]', [x402], [redis], [adaptive], [e2ee].

Pinning >=2 is no longer necessary. That advice existed because a bare pip install venice-ai on Python 3.12 or older silently resolved to v1.3.x. No v1 line was ever published under venice-py, so there is nothing wrong to land on — an unsupported interpreter now fails loudly instead.

venice-ai is not yanked and stays on PyPI permanently, so existing lockfiles keep resolving. A metadata-only bridge release follows shortly, after which pip install venice-ai also lands a working install — it just arrives under the new name.

Also in this release

• Bundled skills renamed to venice-py, venice-py-multimodal, venice-py-production, venice-py-x402. venice-py skills install removes superseded venice-ai* directories it finds, so upgrading doesn't leave both generations installed and triggering against each other. A directory is only removed when its SKILL.md identifies it as one of ours.
• CLI data moved from ~/.venice/ to ~/.venice-py/, migrated automatically on first use, with permissions tightened (conversations/ to 0700, config.yaml to 0600). The old directory is left exactly as it was — it may hold the official CLI's data.
• User-Agent is now venice-py/<version>.
• The CLI identifies itself as venice-py in --version and --help, instead of Venice AI CLI.

Fixed

__version__ is resolved from the installed distribution's metadata, and that lookup sat inside a bare except Exception that fell back to a hardcoded literal — so any mismatch between the looked-up name and the built distribution would have frozen it silently, misreporting the version in every request's User-Agent. A test now asserts the two cannot drift apart.

---

Full detail in the CHANGELOG.

v2.1.0 — the CLI command is now venice-py

Unofficial, community-maintained SDK for Venice.ai. Not affiliated with or endorsed by Venice AI.
Requires Python 3.13+.

pip install --upgrade 'venice-ai>=2'

The CLI command is now venice-py. If you use the [cli] extra, this release needs
a few minutes of your attention. The Python library API is unchanged.

Why the rename

Venice's official CLI — veniceai-cli,
published to npm in March 2026 — installs a binary named venice. As of v2.0.0, so did
this SDK's [cli] extra:

npm install -g veniceai-cli          →  bin: { "venice": "dist/index.js" }
pip install 'venice-ai[cli]>=2'      →  console_scripts: venice=venice_ai.cli:cli

With both installed, which program ran depended on PATH order — typically this SDK's
inside an activated virtualenv, and Venice's outside it. Because the two share subcommand
names (chat, image, video, embeddings, models, characters, config), the
collision was silent: venice chat "hi" did not report a conflict, it ran the other
tool and rejected the flags.

We took the name five months after Venice did, on an unofficial SDK, against the vendor's
own official tool. The two are unrelated programs and no longer contend for it.

What you need to do

Update scripts, aliases, and CI steps:

venice chat start        # before
venice-py chat start     # after

Regenerate shell completions. The environment variable is now _VENICE_PY_COMPLETE:

venice-py completion zsh >> ~/.zshrc

Delete the old entry point. Upgrading in place does not remove it. If venice --version
still prints a Venice AI CLI banner after upgrading, a stale script is left over from
v2.0.x and the collision persists — remove it with the environment active:

rm "$(command -v venice)"

Why this is a minor release

The rename touches only the console script, which is optional ([cli] extra) and two days
old. Nothing about the importable library changed: no module paths, signatures, or types
moved. Code that does not shell out to venice needs no changes.

Not the official CLI

This SDK is unofficial and community-maintained. For Venice's official command-line tool,
see veniceai/venice-cli — a separate Node program,
still invoked as venice. Both can be installed side by side.

Links

Documentation ·
CLI Reference ·
CHANGELOG ·
Full diff

v2.0.2 — install-path guardrails and a corrected Getting Started example

Unofficial, community-maintained SDK for Venice.ai. Not affiliated with or endorsed by Venice AI.
Requires Python 3.13+.

pip install --upgrade 'venice-ai>=2'

Documentation and packaging fixes. No API changes.

Fixed

The first code example on the documentation site raised TypeError. The Getting
Started sample constructed a message positionally — UserMessage("Hello, Venice!") —
which Pydantic rejects, since the message models are keyword-only. It now reads
UserMessage(content="Hello, Venice!").

Getting Started gave an installation sequence that could not work. The Claude Code
skills section told readers to run venice skills install after a plain
pip install venice-ai. The venice CLI ships behind the optional [cli] extra, so
that sequence failed on the install command.

Changed

Documented install commands now carry a >=2 floor, and are quoted. On Python 3.12
and below, a bare pip install venice-ai resolves to v1.3.x silently — pip backtracks
to the newest release whose Requires-Python matches, with no warning — so anyone
following v2 documentation on an older interpreter installed v1 and hit confusing import
errors far from the cause. pip install 'venice-ai>=2' produces an explicit failure
naming the reason instead:

$ pip install 'venice-ai>=2'
ERROR: Ignored the following versions that require a different python version:
       2.0.2 Requires-Python <4.0,>=3.13
ERROR: No matching distribution found for venice-ai>=2

The specifiers are also quoted throughout, because [...] is a glob in zsh — the macOS
default shell — where an unquoted pip install venice-ai[cli] fails with
no matches found. This applies to the runtime error hints and docstrings as well.

Requires-Python metadata is unchanged and remains honest. To stay on v1, pin
venice-ai<2.

The migration guide now covers dependency files. A >=2 floor only helps someone
who copies an install command; a bare venice-ai in requirements.txt or
pyproject.toml still resolves to v1.3.x silently on an older interpreter. That is the
common way to land back on v1 when adding the dependency to a project rather than typing
an install.

The Python 3.13 requirement is stated at the point of installation rather than
several hundred lines below it.

Links

Documentation ·
Migration Guide ·
CHANGELOG ·
Full diff

v2.0.1 — messages= now type-checks with plain dicts

Unofficial, community-maintained SDK for Venice.ai. Requires Python 3.13+.

Patch release on top of v2.0.0.

pip install --upgrade 'venice-ai>=2'

Fixed

messages= now type-checks with plain dicts. The annotation was narrower than what
the code actually accepted: OpenAI-wire-shape mappings like {"role": "user", "content": "hi"}
have always been validated and coerced, but type checkers rejected them
(error: List item 0 has incompatible type "dict[str, str]"). The annotation is now the
public ChatMessageParam union, so both forms check cleanly on create(), stream(),
parse(), estimate_cost(), and run_with_tools().

The typed message models remain the documented idiom — they give you completion and
validation at construction — and malformed mappings still raise ValidationError before
the request is sent.

estimate_cost() and run_with_tools() accept mapping messages. Both read the
message list before it reaches the request model, so dict input previously raised
AttributeError on .content (estimate_cost) or left raw dicts in the returned
ToolLoopResult.messages history (run_with_tools). Messages are now normalized at the
method boundary.

Reported in #1 — thanks for the report.

Added

ChatMessageParam, exported from venice_ai.types — the union describing what
messages= accepts: any of the five message models, or a plain Mapping[str, Any]. Use
it to annotate your own message-building helpers.

v2.0.0 — async-first rewrite, video/music/TEE/x402, and bundled agent skills

Unofficial, community-maintained SDK for Venice.ai. Not affiliated with or endorsed by Venice AI.
For official resources see venice.ai.

Requires Python 3.13+. On earlier versions pip install venice-ai resolves to
v1.3.0 with no error or warning — check python --version before installing.

pip install 'venice-ai>=2'             # core SDK
pip install 'venice-ai[cli]>=2'        # + the `venice` CLI

v2 is a full rewrite of v1.3.x. Coverage is now 48 of the 49 endpoints in Venice's
swagger — the one exception is GET /billing/usage, which Venice deprecated upstream
and this SDK deliberately does not implement.

Breaking changes

v1.3.x	v2.0.0
Python 3.11 / 3.12	Python 3.13+
VeniceClient (sync)	SyncVeniceClient
AsyncVeniceClient	VeniceClient — now async by default
client.image.generate(...)	client.image.create(...)
client.image.get_available_styles()	client.image.list_styles()
client.billing.get_usage(...)	client.billing.get_usage_history(...) (cursor paginated)
client.get_model_pricing(id)	(await client.models.get(id)).model_spec.pricing
resp["data"] (TypedDict)	resp.data (Pydantic model)
venice_ai.types.images	venice_ai.types.api.images
max_tokens=	max_completion_tokens=

There are no deprecation aliases — the old names raise AttributeError or ImportError.
venice lint <path> flags v1, OpenAI-style, and non-idiomatic patterns in your code,
which is the fastest way to find what needs changing.

Full details: Migration Guide.

What's new

Video and music generation. client.video and client.music wrap Venice's async
job endpoints. client.video.run(...) returns a VideoJob that manages the whole
submit → poll → wait → download → cleanup lifecycle, with async with semantics that
guarantee server-side cleanup. Includes quotes, Seedance reference-audio and
reference-video (R2V) inputs, face-media consents, and client.video.transcribe().

Confidential compute. Full client-side Intel TDX attestation verification
(DcapTdxVerifier, fail-closed), per-request integrity proofs via
client.tee.get_signature(...), and client-side end-to-end encryption.

x402 wallet billing on EVM and Solana. client.x402.top_up_with(...) for
EVM/Base and top_up_with_solana(...) for USDC-on-Solana, plus SIWE and SIWS header
signing for the read endpoints. Both paths live-verified end-to-end against Venice's
facilitator.

Typed responses throughout. Endpoints that returned TypedDicts now return
Pydantic models. You can pass a Pydantic model directly as response_format= and read
it back off response.parsed.

No more hardcoded model IDs. client.models.resolve_chat(), resolve_image(),
resolve_video(), resolve_tts(), resolve_asr(), resolve_embedding(),
resolve_cheapest_video() — one capability-filtered call each.

Ergonomics. ChatStream.text_deltas() and .collect(), run_with_tools() for
tool loops, tool_from_function() to build a Tool from type hints, .save() /
.save_all() on image and audio responses, client.gather(max_concurrency=N).

Operations. Intelligent rate-limit scheduling with an optional Redis backend, cost
estimation via estimate_cost() and CostTracker, and venice health for
connectivity and balance diagnostics.

Bundled Claude Code skills. Four agent skills ship inside the package.
venice skills install (requires the [cli] extra) copies them into .claude/skills/
so Claude Code writes idiomatic v2 code against this SDK instead of guessing at
OpenAI-shaped calls.

74 additions and 45 fixes in total — see the
CHANGELOG for the
complete list.

Links

Documentation ·
Migration Guide ·
API Reference ·
Examples

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...