vocence 0.4.1

Official Python SDK for the Vocence Developer API — TTS, STT, voice cloning, voice design, and real-time voice agents.

Vocence Python SDK

Official Python client for the Vocence Developer API.

pip install vocence              # REST + WebSocket
pip install "vocence[audio]"     # adds Turn.play() and the mic ↔ agent live-chat helper

Quickstart

from vocence import Vocence

client = Vocence(api_key="voc_live_...")

# 1. Browse the catalog of pre-defined speakers
for v in client.voices.builtin():
    print(v.id, v.name, "—", v.description)

# 2. Synthesize text in one of them
audio = client.tts.speak(text="Hello from Vocence!", voice="design-aria")
print(audio.audio_url)

# 3. Transcribe an audio clip
text = client.stt.transcribe(audio_path="clip.wav", language="English").text
print(text)

Async usage mirrors the sync API exactly:

import asyncio
from vocence import AsyncVocence

async def main() -> None:
    async with AsyncVocence(api_key="voc_live_...") as client:
        audio = await client.tts.speak(text="Hello", voice="design-aria")
        print(audio.audio_url)

asyncio.run(main())

Voice agents over WebSocket

import asyncio
from vocence import AsyncVocence

async def main() -> None:
    async with AsyncVocence(api_key="voc_live_...") as client:
        async with client.agents.session("agent-id") as session:
            await session.send_text("What's the weather in Tokyo?")
            async for event in session:
                print(event)
                if event.type == "turn_end":
                    break

asyncio.run(main())

The session yields typed events: ready, transcript, token, tool_call_started, tool_call_completed, audio_meta, audio (binary PCM16), audio_end, turn_end, error.

For one-shot turns (no streaming), use the higher-level conversation API:

async with client.agents.conversation("agent-id") as conv:
    turn = await conv.say("What's the weather in Tokyo?")
    print(turn.text)                 # "It's 19 degrees..."
    open("reply.pcm", "wb").write(turn.audio)
    print(turn.audio_meta)            # {'sample_rate': 24000, 'frame_ms': 40, ...}

The sync Vocence client exposes client.agents.session(agent_id) as a blocking context manager — events are iterated with a normal for loop:

with Vocence(api_key="voc_live_...").agents.session("agent-id") as sess:
    sess.send_text("hi")
    for event in sess:
        if event.type == "turn_end":
            break

CLI

$ vocence login                          # opens a browser → approve → key saved
$ vocence account                        # show plan, credits remaining, key count
$ vocence usage                          # last 20 API requests
$ vocence keys list / create / revoke
$ vocence agents list / show / create / delete

# voices
$ vocence voices                         # list built-in speakers
$ vocence speak "Hello" --voice design-aria -o out.wav
$ vocence clone path/to/clip.wav --name "My Voice"
$ vocence design "warm female narrator"   # interactive design + save

# audio
$ vocence transcribe clip.wav --language English
$ vocence chat <agent-id>                 # text REPL, plays the reply
$ vocence voice <agent-id>                # push-to-talk mic REPL  (needs vocence[audio])

Config is written to ~/.vocence/config.json. Override the key with the VOCENCE_API_KEY environment variable on any command.

Errors

from vocence import Vocence, errors

client = Vocence(api_key="voc_live_invalid")
try:
    client.tts.speak(text="x", voice="design-aria")
except errors.AuthenticationError as e:
    print("bad key:", e)
except errors.InsufficientCreditsError as e:
    print("top up:", e)
except errors.RateLimitError as e:
    print("slow down, retry after:", e.retry_after)

API parity

The SDK covers 100% of the public REST + WS surface documented at vocence.ai/docs/api. See CHANGELOG.md for what shipped in each release.

License

Apache 2.0 — see the repo-root LICENSE.