Skip to content

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 endpointxVoice
POST /v1/audio/speechSupported. See Text to speech
POST /v1/audio/transcriptionsSupported. See Speech to text
WS /v1/realtime?intent=transcriptionSupported. See Realtime transcription
GET /v1/models, GET /v1/models/{id}Supported, with extra fields. See Models
POST /v1/audio/translationsNot supported
Realtime conversations (speech to speech)Not supported
Chat, embeddings, images and the restNot 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-tts and cadence-stt. OpenAI ids such as whisper-1, gpt-4o-transcribe and tts-1 are rejected with invalid_model.
  • Voice ids are xVoice's. OpenAI voices such as alloy and nova are rejected with invalid_voice. See Voices.
  • Each model declares what it accepts. Read capabilities and speech_options on the model instead of assuming. A request for something a model does not offer is refused, never quietly substituted.

Text to speech ​

  • response_format is wav, pcm or mp3. flac, opus and aac are refused.
  • speed must be 1.0.
  • instructions is accepted and ignored.

Speech to text ​

  • response_format is json or text. verbose_json, srt and vtt are not available, so there are no word or segment timestamps.
  • timestamp_granularities, include and chunking_strategy have 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_detection must be null.
  • Audio is 24 kHz mono PCM16 only.
  • Authentication uses the API key in the Authorization header. Ephemeral client keys and WebRTC are not available.
  • Unknown events and fields are errors rather than being ignored.

See Realtime transcription for the details.

xVoice is a product of Stochastic Inc.