Appearance
OpenAI compatibility
The xVoice API follows OpenAI's audio API. Code written for OpenAI's speech, transcription and realtime transcription endpoints runs against xVoice after two changes: the base URL and the API key.
python
from openai import OpenAI
client = OpenAI(api_key="xv_...", base_url="https://api.xvoice.dev/v1")js
import OpenAI from 'openai'
const client = new OpenAI({ apiKey: 'xv_...', baseURL: 'https://api.xvoice.dev/v1' })The client's own features work unchanged: automatic retries on 429 and 5xx, timeouts, async clients, raw responses and the streaming helpers. Error responses use OpenAI's envelope, so the SDK raises its usual exceptions.
Endpoints
| OpenAI endpoint | xVoice |
|---|---|
POST /v1/audio/speech | Supported. See Text to speech |
POST /v1/audio/transcriptions | Supported. See Speech to text |
WS /v1/realtime?intent=transcription | Supported. See Realtime transcription |
GET /v1/models, GET /v1/models/{id} | Supported, with extra fields. See Models |
POST /v1/audio/translations | Not supported |
| Realtime conversations (speech to speech) | Not supported |
| Chat, embeddings, images and the rest | Not supported |
xVoice adds GET /v1/voices, which lists the voices, and GET /v1/me, which tells you what a key belongs to.
Differences
Models and voices
- Model ids are xVoice's. Use
cadence-ttsandcadence-stt. OpenAI ids such aswhisper-1,gpt-4o-transcribeandtts-1are rejected withinvalid_model. - Voice ids are xVoice's. OpenAI voices such as
alloyandnovaare rejected withinvalid_voice. See Voices. - Each model declares what it accepts. Read
capabilitiesandspeech_optionson the model instead of assuming. A request for something a model does not offer is refused, never quietly substituted.
Text to speech
response_formatiswav,pcmormp3.flac,opusandaacare refused.speedmust be1.0.instructionsis accepted and ignored.
Speech to text
response_formatisjsonortext.verbose_json,srtandvttare not available, so there are no word or segment timestamps.timestamp_granularities,includeandchunking_strategyhave no effect.- Files are limited to 25 MB and 10 minutes.
Realtime transcription
- There is no server-side turn detection. Your client decides when an utterance ends and sends
input_audio_buffer.commit.turn_detectionmust benull. - Audio is 24 kHz mono PCM16 only.
- Authentication uses the API key in the
Authorizationheader. Ephemeral client keys and WebRTC are not available. - Unknown events and fields are errors rather than being ignored.
See Realtime transcription for the details.