Install & Compatibility
Where this runs
tested against v1.11.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.763s · 60.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.3s · import 0.735s · 60MB
58MB installed
● package 58MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Vapi
✓ from vapi import Vapi
✗ from vapi_server_sdk import VapiClient
The `VapiClient` import is common in the TypeScript SDK; for Python, use `from vapi import Vapi` for the synchronous client.
AsyncVapi
✓ from vapi import AsyncVapi
Use this for the asynchronous client to make non-blocking API calls.
ApiError
✓ from vapi.core.api_error import ApiError
Base class for API-specific exceptions (4xx and 5xx responses).
This quickstart demonstrates how to instantiate both the synchronous `Vapi` and asynchronous `AsyncVapi` clients using your Vapi API key, preferably loaded from an environment variable. It illustrates basic API interaction for creating a call and includes error handling for `ApiError` responses. Replace placeholder API calls with actual methods from the Vapi API documentation, such as `client.calls.create()` with relevant `assistant_id` and `phone_number_id`.
import os
import asyncio
from vapi import Vapi, AsyncVapi
from vapi.core.api_error import ApiError
# Synchronous client example
def create_sync_call():
client = Vapi(
token=os.environ.get('VAPI_API_KEY', 'YOUR_VAPI_PRIVATE_API_KEY')
)
try:
# Example: create an outbound call (replace with actual assistant_id and phone_number_id)
print("Attempting to create a synchronous call...")
# This method is illustrative; actual API calls will vary based on Vapi's current API.
# Refer to Vapi's official documentation for up-to-date API methods and parameters.
# Example: call = client.calls.create(assistant_id="asst_YOUR_ID", phone_number_id="pn_YOUR_ID", customer_number="+15551234567")
# For demonstration, we'll simulate a success.
# In a real scenario, you would call a Vapi API method, e.g., client.calls.create(...)
print("Synchronous call creation simulated successfully.")
except ApiError as e:
print(f"Synchronous API Error: Status {e.status_code}, Body: {e.body}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
# Asynchronous client example
async def create_async_call():
client = AsyncVapi(
token=os.environ.get('VAPI_API_KEY', 'YOUR_VAPI_PRIVATE_API_KEY')
)
try:
print("Attempting to create an asynchronous call...")
# Similar to sync client, actual API calls depend on Vapi's current API.
# Example: call = await client.calls.create(assistant_id="asst_YOUR_ID", phone_number_id="pn_YOUR_ID", customer_number="+15551234567")
# For demonstration, we'll simulate a success.
await asyncio.sleep(0.1) # Simulate async operation
print("Asynchronous call creation simulated successfully.")
except ApiError as e:
print(f"Asynchronous API Error: Status {e.status_code}, Body: {e.body}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
if __name__ == "__main__":
print("--- Synchronous Vapi Client Example ---")
create_sync_call()
print("\n--- Asynchronous Vapi Client Example ---")
asyncio.run(create_async_call())
Debug
Known issues
breakingSeveral legacy API endpoints have been removed as part of Vapi's API modernization, including `/logs`, `/workflow/{id}`, `/test-suite`, and `/knowledge-base` related paths.fixMigrate to the new evaluation system, call artifacts, monitoring, and updated workflow/model configurations. Refer to the Vapi changelog for details on replacements.
affects: Prior to latest API version (v2 introduced)
breakingThe `knowledgeBaseId` property has been removed from all model configurations due to a knowledge base architecture change.fixAdjust model configurations to remove `knowledgeBaseId` and integrate knowledge directly into model settings or use updated mechanisms.
affects: Prior to latest API version (v2 introduced)
deprecatedThe `AssemblyAITranscriber.wordFinalizationMaxWaitTime` and `FallbackAssemblyAITranscriber.wordFinalizationMaxWaitTime` properties are deprecated.fixUtilize Vapi's smart endpointing plans for improved speech timing control, more precise conversation flow management, and enhanced end-of-turn detection capabilities.
affects: 1.x.x (exact deprecation version not specified, but mentioned in September 2025 changelog)
gotchaThe SDK is programmatically generated. Direct code contributions (outside of README) will be overwritten in future releases.fixFor feature requests or bug fixes that require code changes, it's recommended to open an issue first to discuss with the VapiAI team. Pull requests can serve as proof-of-concept but may not be merged directly.
affects: All versions
gotchaRequests have a default timeout of 60 seconds.fixConfigure the `timeout` option at the client initialization level or for individual requests using `request_options={'timeout_in_seconds': N.0}` to adjust the timeout. affects: All versions
Errors
Common errors & fixes
vapi.core.api_error.ApiError: HTTP status code (4xx or 5xx) received
The Vapi API returned an error response (e.g., bad request, unauthorized, server error).
fixCatch `ApiError` exceptions and inspect `e.status_code` and `e.body` for specific error details. Verify API token, request parameters, and review Vapi service status.
Call failed due to 'assistant-request-failed' or 'assistant-request-returned-error'
Your server URL, configured to dynamically provide an assistant, failed to respond or returned an error.
fixEnsure your server is running, publicly accessible (e.g., via ngrok for local development), and returns a valid assistant configuration. Check server logs for errors.
call.start.error-subscription-insufficient-credits
Your Vapi account has insufficient credits to initiate the call.
fixAdd more credits to your Vapi account or enable auto-reload for your subscription.
401-incorrect-api-key, 403-model-access-denied, 429-exceeded-quota for LLM/Voice Provider
Issues with API keys, permissions, or rate limits for integrated LLM or voice providers (e.g., OpenAI, ElevenLabs).
fixVerify the API key for the specific provider is correct, ensure it has access to the requested models, and check if you've exceeded any rate limits or quotas with that provider.
High loading time and unnecessary warnings at startup in Docker (related to pydantic models)
Reported issue where pydantic model rendering causes performance overhead and warnings in containerized environments.
fixThis is an open issue (#22) on the GitHub repository. Monitor the official repository for updates or workarounds. Optimize environment setup to minimize pydantic re-evaluation if possible, though a direct fix is pending from the library maintainers.
Upgrade
Version history
1.11.1latest on PyPI · released May 20, 2026
Audit
Dependencies
httpxrequiredHTTP client for API requests.
typing-extensionsrequiredBackports and future-proofing for Python's typing module.
pydanticrequiredData validation and settings management using Python type hints.
pydantic-corerequiredCore validation logic for Pydantic.