Skip to content

Quickstart ​

Go from signup to a round trip: generate speech, then transcribe it back. It takes about five minutes.

1. Create an account and a key ​

  1. Sign up at app.xvoice.dev. An organization and a project are created with your account, so there is nothing else to set up.
  2. Verify your email address. You need to before you can sign in, and it adds your free starting credit, so your first calls cost you nothing.
  3. Open Projects → your project → API keys and create a key. Choose test while you are building.

The secret is shown only once, when you create the key. Copy it now. If you lose it, create a new key.

bash
export XVOICE_API_KEY=xv_...

2. Install an SDK ​

xVoice works with the official OpenAI SDKs. Point one at the xVoice base URL:

bash
pip install openai
bash
npm install openai
python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XVOICE_API_KEY"],
    base_url="https://api.xvoice.dev/v1",
)
js
import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.XVOICE_API_KEY,
  baseURL: 'https://api.xvoice.dev/v1',
})

Everything else about the client works as usual: retries, timeouts, async calls and the streaming helpers. If you are moving code over from OpenAI, read OpenAI compatibility for what differs.

3. Generate speech ​

python
speech = client.audio.speech.create(
    model="cadence-tts",
    voice="clara",
    input="Hello, this is a round trip through xVoice.",
    response_format="wav",
)
speech.write_to_file("speech.wav")
js
import fs from 'node:fs'

const speech = await client.audio.speech.create({
  model: 'cadence-tts',
  voice: 'clara',
  input: 'Hello, this is a round trip through xVoice.',
  response_format: 'wav',
})
fs.writeFileSync('speech.wav', Buffer.from(await speech.arrayBuffer()))
bash
curl https://api.xvoice.dev/v1/audio/speech \
  -H "Authorization: Bearer $XVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cadence-tts",
    "voice": "clara",
    "input": "Hello, this is a round trip through xVoice.",
    "response_format": "wav"
  }' \
  --output speech.wav

voice takes an xVoice voice id. See Voices for the full list.

4. Transcribe it back ​

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

print(result.text)
js
const result = await client.audio.transcriptions.create({
  model: 'cadence-stt',
  file: fs.createReadStream('speech.wav'),
})

console.log(result.text)
bash
curl https://api.xvoice.dev/v1/audio/transcriptions \
  -H "Authorization: Bearer $XVOICE_API_KEY" \
  -F model=cadence-stt \
  -F file=@speech.wav
json
{"text": "Hello, this is a round trip through xVoice.", "usage": {"type": "duration", "seconds": 3.0}}

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.

Next steps ​

Troubleshooting ​

What you seeWhat to do
401 missing_api_keyNo Authorization header arrived. Check that the base URL ends in /v1
401 invalid_api_keyThe key is wrong or has been revoked. Create a new one
400 invalid_modelUse cadence-tts for speech and cadence-stt for transcription
402 insufficient_creditsYour balance is empty. Top up under Billing
429 rate_limit_exceededWait for the number of seconds in retry-after, then retry

Every error includes a request_id. Include it when you contact support, so we can find the exact request.

xVoice is a product of Stochastic Inc.