Python SDK

pip install voixa

from voixa import Voixa

vx = Voixa()  # reads VOIXA_API_KEY; create a key in Studio -> API keys
# or: Voixa(api_key="...", base_url="https://api.voixa.vovix.io/v1", timeout=30)

voices = vx.voices(language="en")["voices"]
clip = vx.say(
    voice_id=voices[0]["voiceId"],
    text="The lighthouse keeper switched the lamp on at dusk.",
    project="episode-12",  # optional: group clips by content
)
print(clip["url"], clip["durationSec"])  # signed WAV URL, valid for 1 hour

# Play it as it arrives
for chunk in vx.stream(voice_id="vi-truc-ly", text="Xin chào, Voixa có thể giúp gì?", sample_rate=16000):
    player.write(chunk)

# Or write it to a file
with vx.stream(voice_id="vi-truc-ly", text="Xin chào!", format="wav") as s:
    print(s.sample_rate, s.tokens)
    s.save("hello.wav")  # or: open("hello.wav", "wb").write(s.read())

from voixa import estimate_tokens

account = vx.account()["account"]
account["tokens"]  # {available, freeToday, dailyFree, balance, usedToday, refillsAt, rates, unlimited}
rates = account["tokens"]["rates"]
estimate_tokens(rates, language="vi", chars=1200)   # -> 1200
estimate_tokens(rates, design_options=3)             # a voice design with three options
estimate_tokens(rates, audio_seconds=600)            # ten minutes of transcription
page = vx.usage(limit=20)                            # every spend, refund and top-up

languages = vx.languages()["languages"]   # codes, labels, limits, clone-recording guides
samples = vx.samples(language="fr")        # built-in voices with public sample URLs
voice = vx.get_voice("en-alba")["voice"]

design = vx.design_voice(
    description="An old man in his seventies, hoarse and deep, speaking slowly",
    language="vi",  # any language `languages()` marks `designable`
    count=3,        # 1-3 options, `rates["design"]` tokens each
)["design"]
done = vx.wait_for_design(design["designId"])  # about a minute per option
for c in done["candidates"]:
    print(c["index"], c["status"], c.get("url"))  # listen, then pick

voice = vx.save_design(done["designId"], candidate=1, name="Grandpa Ba", gender="male")
vx.say(voice_id=voice["voiceId"], text="Ngày ấy, ông vẫn nhớ con đường làng.")

# Or in one call, keeping the first option:
narrator = vx.create_voice_from_description(
    description="A calm female narrator, warm and clear", language="en", name="Narrator",
)

vx.list_designs(limit=10)          # your designs, newest first
vx.get_design(design["designId"])  # one design with its options
vx.delete_design(design["designId"])  # saved voices are kept

voice = vx.create_voice(
    name="Studio narrator",
    language="en",
    gender="female",
    audio="reference.wav",  # 3-10 s of clean speech, WAV or MP3, max 10 MB
    # audio accepts bytes, a path, or a binary file object: open("ref.mp3", "rb")
    # format="mp3",          # wav by default
    # ref_text="...",        # what the speaker says; helps Chinese, Japanese, Korean
)
vx.say(voice_id=voice["voiceId"], text="Hello from my own voice.")

vx.update_voice(voice["voiceId"], shared=True)       # let every Voixa account use it
vx.update_voice(voice["voiceId"], name="Narrator", description=None)  # None clears the description
vx.delete_voice(voice["voiceId"])

episode = vx.make_podcast(voice_id="vi-truc-ly", title="Episode 12", text=script, project="my-show")
episode["url"]          # one WAV, signed for an hour
episode["durationSec"]  # e.g. 4800 for an 80-minute episode

# or without waiting:
clip = vx.create_podcast(voice_id="en-alba", text=script)["clip"]
clip["parts"], clip.get("partsDone")  # progress while status is "processing"

t = vx.transcribe_file(
    audio="interview.mp3",  # bytes, a path or a binary file object; files are streamed from disk
    title="Interview with the lighthouse keeper",
    # language="vi",        # optional: Voixa detects it well on its own
    # task="translate",     # recognise any language, return English
    # words=True,           # per-word timestamps
    # prompt="Voixa, Vovix",  # spelling hints for names and jargon
)
print(t["language"], t["durationSec"], t["text"])
print(t["segments"][0])  # {"id", "start", "end", "text"}
print(t["srtUrl"])       # signed SRT/VTT/TXT/JSON URLs, valid for 1 hour

transcript = vx.transcribe(audio="talk.m4a")["transcript"]
done = vx.wait_for_transcript(transcript["transcriptId"])
# progress while processing: doneSec / durationSec, jobStatus

items = vx.list_transcripts(project="episode-12")["items"]   # no text in lists
full = vx.get_transcript(items[0]["transcriptId"])            # text + segments + URLs
vx.delete_transcripts([transcript["transcriptId"]])           # also deletes the upload

projects = vx.projects()["projects"]                  # groups with clip counts
page = vx.list_clips(project="episode-12")            # newest first
from_api = vx.list_clips(source="api")                # clips made with an API key (vs. "studio")
podcasts = vx.list_clips(kind="podcast", limit=50)
more = vx.list_clips(project="episode-12", cursor=page.get("cursor"))
vx.delete_clips([c["clipId"] for c in page["items"]])

share = vx.share_clip(clip["clipId"])   # {"shareUrl": "https://voixa.vovix.io/s/...", "shared": True}
vx.unshare_clip(clip["clipId"])         # the link stops working
vx.get_clip(clip["clipId"])
vx.wait_for(clip["clipId"], timeout=300)

from voixa import VoixaError

try:
    vx.say(voice_id="vi-truc-ly", text=long_text)
except VoixaError as e:
    if e.code == "INSUFFICIENT_TOKENS":
        print(f"Need {e.needed}, have {e.available}; free tokens refill at {e.refills_at}")
    elif e.code == "TIMEOUT":
        ...  # still processing: poll later with vx.wait_for(...)
    else:
        raise