Quickstart

From nothing to a transcript. The target is five minutes.

1. Get a key

1. Sign up in the dashboard. One organization and one project are created with the account, so there is nothing to set up first.
2. Verify your email address — the link is required to sign in.
3. Open Projects → your project → API keys and create one. Choose test while you are building.

The secret is shown once, at creation. It is stored hashed, so a lost key is replaced rather than recovered.

export XVOICE_API_KEY=sk_test_...
export XVOICE_BASE_URL=https://your-xvoice-host/v1   # http://localhost:8000/v1 locally

Verifying your email is what grants the free starting credit, so the first calls cost nothing out of pocket. See Rate limits and billing.

2. Point a client at it

xVoice speaks the OpenAI audio API, so use the official client:

pip install openai

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["XVOICE_API_KEY"], base_url=os.environ["XVOICE_BASE_URL"])

Nothing else about the client changes. Retries, timeouts, with_raw_response, the async variant and the streaming helpers all behave as they do against OpenAI.

3. See what you can call

for model in client.models.list():
    print(model.id, model.type, model.capabilities)

capabilities is worth reading rather than assuming: it says which of batch, streaming and realtime a model actually serves, and the API enforces it. See Models and voices.

4. Speak something

speech = client.audio.speech.create(
    model="xvoice-tts1",
    voice="neutral-female",
    input="Hello, this is a round trip through xVoice.",
    response_format="wav",
)
speech.write_to_file("speech.wav")

Voices are xVoice ids — client.audio.speech.create takes ours, not OpenAI's. List them with GET /v1/voices.

5. Transcribe it back

with open("speech.wav", "rb") as audio:
    result = client.audio.transcriptions.create(model="xvoice-stt1", file=audio)

print(result.text)
print(result.usage.seconds, "seconds billed")

That is the round trip. Both calls now appear in the dashboard under Usage and Projects → Request logs, with their cost, latency and request id.

6. Then what

• Streaming, so long text starts playing before it is finished: Text to speech.
• A live microphone rather than a file: Realtime transcription.
• Handle failures properly before you ship: Errors.
• Working scripts for all of the above: Example scripts.

If something goes wrong

What you see	What it means
401 missing_api_key	No Authorization header reached us — check the base URL has /v1 on it
401 invalid_api_key	The key is wrong, revoked, or from another deployment
400 invalid_model	The id does not exist, or is not a model for this endpoint — run client.models.list(); ids are ours, not OpenAI's
402 insufficient_credits	The balance is empty — top up under Billing
429 rate_limit_exceeded	Back off; retry-after says how long

Every error carries a request_id. Quote it and we can find the exact request.