Appearance
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
- Sign up at app.xvoice.dev. An organization and a project are created with your account, so there is nothing else to set up.
- 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.
- 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 openaibash
npm install openaipython
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.wavvoice 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.wavjson
{"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
- Stream speech so long text starts playing right away.
- Transcribe live audio from a call or a microphone.
- Handle errors before you ship.
- Run the realtime example, a complete client you can adapt.
Troubleshooting
| What you see | What to do |
|---|---|
401 missing_api_key | No Authorization header arrived. Check that the base URL ends in /v1 |
401 invalid_api_key | The key is wrong or has been revoked. Create a new one |
400 invalid_model | Use cadence-tts for speech and cadence-stt for transcription |
402 insufficient_credits | Your balance is empty. Top up under Billing |
429 rate_limit_exceeded | Wait 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.