xAI Voice (Text to Speech)

The following voices are available. Voice names are case-insensitive. For example, ara, Ara, and ARA are accepted.

You can convert text to speech by using either the OCI OpenAI-compatible Audio Speech API or WebSocket streaming.

The OCI OpenAI-compatible Audio Speech API doesn’t support realtime streaming. For streaming text-to-speech, use the WebSocket endpoint.

Use the OCI OpenAI-compatible Audio Speech API to generate audio from a single request.

OCI OpenAI-Compatible Endpoint

https://inference.generativeai.{region}.oci.oraclecloud.com/openai/v1

In the request, call the xai.grok-tts model and use one of the Grok Voice voices listed in this topic. Don’t use OpenAI text-to-speech model names or OpenAI voice names.

Specify these values in the standard OpenAI-compatible audio speech request:

• model: xai.grok-tts
• input: Text to convert to speech
• voice: One of the supported Grok Voice voices, such as ara, eve, leo, rex, or sal
• response_format: Audio response format, such as mp3

Put xAI-specific options, such as language and output_format, in extra_body.

For example, use extra_body for settings such as:

• language
• output_format.sample_rate
• output_format.bit_rate

Use WebSocket streaming for real-time or interactive text-to-speech workflows. With this option, you send text to the service as messages and receive audio as base64-encoded audio chunks.

OCI WebSocket endpoint:

wss://inference.generativeai.{region}.oci.oraclecloud.com/xai/v1/tts

Don’t use the xAI endpoint directly.

Set up the WebSocket connection with xAI text-to-speech query parameters such as:

After opening the WebSocket connection, send text using text.delta messages. Send text.done to indicate the end of the current utterance.

The service returns:

The WebSocket connection can remain open after audio.done, so you can send another text.delta and text.done sequence without reconnecting.

The parameters you use depend on the access option.

For the OCI OpenAI-compatible Audio Speech API, use the OpenAI-compatible audio speech request format. Set model to xai.grok-tts, use a supported xAI voice, and put xAI-specific settings in extra_body.

For WebSocket streaming, use xAI text-to-speech streaming parameters. Configure voice, language, codec, sample rate, and bit rate as WebSocket query parameters. Send text with text.delta messages and finish each utterance with text.done.

Text to Speech supports common audio formats for different use cases.

Text to Speech supports many languages. Use a supported language code, such as en, or use auto for automatic language detection when supported by the access method.

Text to Speech limits depend on the access option.

For longer text, split the content into logical segments, such as paragraphs or sentences. This helps keep each request or text chunk within the character limit and makes it easier to combine the generated audio in order.

For WebSocket streaming, send text by using text.delta messages and send text.done when the current utterance is complete. Each text.delta message must stay within the character limit.

For release and retirement dates and replacement model options, see the Model Retirement Dates (On-Demand Mode).

• Text to Speech on xAI
• Streaming TTS WebSocket on xAI
• Text to Speech on OpenAI

The following examples show the two supported access options. The OCI OpenAI-compatible example uses the OCI OpenAI-compatible endpoint and the xai.grok-tts model. The WebSocket example uses the OCI xAI WebSocket endpoint and xAI streaming parameters.

OCI OpenAI-compatible Audio Speech API

from openai import OpenAI
from oci_openai import OciSessionAuth

client = OpenAI(
    api_key="<not-used>",
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
    http_client=httpx.Client(
        auth=OciSessionAuth(profile_name=<profile>),
        headers={"CompartmentId": <compartment_id>}
    ),
)

speech = client.audio.speech.create(
    model="xai.grok-tts",
    input="hello",
    voice="ara",
    response_format="mp3",
    extra_body={
        "language": "en",
        "output_format": {
            "sample_rate": 44100,
            "bit_rate": 192000
        }
    }
)

audio_file = f"output.mp3"
with open(audio_file, "wb") as f:
    f.write(speech.content)

WebSocket Streaming

import asyncio
import base64
import inspect
import json
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import urlencode

import websockets


CONFIG = {
    "endpoint": "wss://inference.generativeai.us-chicago-1.oci.oraclecloud.com/xai/v1/tts",
    "api_key": "<YOUR GENAI API KEY>",
    "text": "Hi, this is an audio sample.",
    "voice": "eve",
    "language": "en",
    "codec": "mp3",
    "sample_rate": 24000,
    "bit_rate": 128000,
    "output_dir": "./",
}


def tts_url():
    params = {
        "language": CONFIG["language"],
        "voice": CONFIG["voice"],
        "codec": CONFIG["codec"],
        "sample_rate": CONFIG["sample_rate"],
    }
    if CONFIG["codec"] == "mp3":
        params["bit_rate"] = CONFIG["bit_rate"]
    return "{}?{}".format(CONFIG["endpoint"], urlencode(params))


def output_file():
    folder = Path(CONFIG["output_dir"]).expanduser()
    folder.mkdir(parents=True, exist_ok=True)
    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    return folder / "grok_tts_{}.{}".format(timestamp, CONFIG["codec"])


async def main():
    if CONFIG["api_key"] == "<YOUR GENAI API KEY>":
        raise ValueError("Set api_key before running this sample.")

    path = output_file()
    headers = {"Authorization": "Bearer {}".format(CONFIG["api_key"])}
    header_arg = (
        "additional_headers"
        if "additional_headers" in inspect.signature(websockets.connect).parameters
        else "extra_headers"
    )

    async with websockets.connect(tts_url(), **{header_arg: headers}) as ws:
        await ws.send(json.dumps({"type": "text.delta", "delta": CONFIG["text"]}))
        await ws.send(json.dumps({"type": "text.done"}))

        with open(str(path), "wb") as audio_file:
            async for message in ws:
                event = json.loads(message)
                if event["type"] == "audio.delta":
                    audio_file.write(base64.b64decode(event["delta"]))
                elif event["type"] == "audio.done":
                    print("Saved audio to {}".format(path))
                    break
                elif event["type"] == "error":
                    raise RuntimeError(event.get("message", message))


if __name__ == "__main__":
    asyncio.run(main())