voicepilot-sdk 0.1.6

Official Python SDK for high-fidelity voice and conversational AI.

🚀 VoicePilot Python SDK

The official Python client for the VoicePilot high-fidelity voice and conversational AI platform.

Installation

pip install voicepilot-sdk
# For real-time conversational features:
pip install voicepilot-sdk[ws]

Quick Start

Initialize Client

from voicepilot import VoicePilotClient

# Generate your key at https://openclaw.intelligens.app
client = VoicePilotClient(api_key="sk_platform_your_key_here")

Text-to-Speech (TTS)

# Standard TTS (returns base64 string)
response = client.tts.create("Hello, welcome to VoicePilot!", voice="anushka")

# Streaming TTS (yields raw WAV bytes directly)
with open("output.wav", "wb") as f:
    for chunk in client.tts.stream("Hello from the streaming API!", voice="anushka"):
        f.write(chunk)

Speech-to-Text (STT)

result = client.stt.transcribe("speech_sample.wav")
print(f"Transcription: {result.transcript}")

Agent Management & Text Chat

# Create and delete agents
agent = client.agents.create(name="Support", system_prompt="You are a helpful assistant.")
client.agents.delete(agent.id)

# Stateless text chat with an agent (no WebSockets needed)
response = client.agents.chat(
    agent_id=agent.id,
    text="Hello!",
    history=[{"role": "user", "content": "Hi there"}]
)
print(response.reply_text)

📞 Call Lifecycle (Create & End Calls)

The SDK provides dedicated methods to reserve call sessions and finalize them, which is essential for billing, analytics, and triggering webhooks.

1. Manual Create & End (Recommended for custom integrations):

# Create a conversation log *before* connecting your frontend WebSockets
conv = client.conversations.create(agent_id="my_agent_id")
print(f"Pass this ID to your frontend: {conv['conversation_id']}")

# ... User completes the call on the frontend ...

# Explicitly end the call to finalize logs and trigger your webhooks
client.conversations.end(conv['conversation_id'])

2. Automatic Lifecycle via Built-In WebSocket Client:

# The `connect` context manager automatically calls `conversations.create()` 
# when entering the block, and cleanly closes the socket upon exiting.
with client.agents.connect(agent_id="my_agent_id") as session:
    # Get the auto-generated conversation ID
    print(f"Active Session: {session.conversation_id}")
    
    session.send("Tell me a story.")
    for message in session.listen():
        if message.type == "agent.response":
            print(f"Agent: {message.text}")

Error Handling

The SDK provides a typed exception hierarchy for easy error management.

from voicepilot.exceptions import ValidationError, AuthenticationError

try:
    client.tts.create("")
except ValidationError as e:
    print(f"Oops: {e}")
except AuthenticationError:
    print("Check your API key!")

Development

• Tests: pytest tests/
• Build: python -m build