语音

curl -s https://api.x.ai/v1/realtime/client_secrets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "expires_after": {
      "seconds": 300
    }
  }'

const response = await fetch("https://api.x.ai/v1/realtime/client_secrets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    expires_after: {
      seconds: 300,
    },
  }),
});

const data = await response.json();
console.log(JSON.stringify(data, null, 2));

import json
import os

import requests

response = requests.post(
    "https://api.x.ai/v1/realtime/client_secrets",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "expires_after": {
            "seconds": 300,
        },
    },
)

print(json.dumps(response.json(), indent=2))

{
  "expires_after": {
    "seconds": 300
  }
}

{
  "value": "xai-realtime-client-secret-...",
  "expires_at": 1774274445
}

No parameters.

{
  "phone_number": {
    "phone_number_id": "phone_abc123",
    "team_id": "00000000-0000-0000-0000-000000000000",
    "phone_number": "+18005550199",
    "name": "Support SIP trunk",
    "webhook_id": "webhook_abc123",
    "origin": "byo_trunk",
    "sip_host": "sip.voice.x.ai",
    "sip_auth": {
      "allowed_addresses": [
        "203.0.113.0/24"
      ]
    },
    "created_at": "2026-06-19T00:00:00Z",
    "updated_at": "2026-06-19T00:00:00Z"
  },
  "webhook": {
    "webhook_id": "webhook_abc123",
    "dispatch_signing_secret": "whsec_..."
  }
}

实时

WebSocket 端点：wss://api.x.ai/v1/realtime

通过 WebSocket 与 Grok 模型进行实时语音对话。连接以升级为 WebSocket（状态 101）的 HTTP GET 请求开始。连接后，客户端和服务器交换 JSON 消息，以配置会话、流式传输音频并接收响应。对于 SIP 呼叫，请使用 `realtime.call.incoming` webhook 中的 `call_id` 建立连接。

完整的 Schema 和示例：/voice-realtime.ws.json

查询参数

• call_id（string, optional）— 来自 `realtime.call.incoming` webhook 的 SIP 呼叫标识符。提供后，WebSocket 将连接到该入站 SIP 呼叫。使用 xAI API 密钥进行身份验证； SIP `call_id` 会话不支持临时客户端密钥。

• model（string, optional, default: grok-voice-latest）— 用于会话的模型。提供 `call_id` 时会被忽略，因为会话已绑定到入站 SIP 呼叫。对于直接 WebSocket 会话，使用 grok-voice-latest 可获得最佳体验。

• reasoning.effort（string, optional, default: high）— 控制模型是否使用推理。默认为 `high`。

客户端消息

• session.update— 更新会话配置，例如系统 prompt、语音、音频格式、轮次检测和工具。

• input_audio_buffer.append— 将 Base64 编码的音频数据块附加到输入缓冲区。服务器不会发回相应的消息。

• input_audio_buffer.commit— 将音频缓冲区作为用户消息提交。仅当 `turn_detection` 类型为 `null` 时可用。由服务器的 `input_audio_buffer.committed` 确认。

• conversation.item.create— 创建新的对话项。它可以是用户文本消息、用于初始化历史记录的 assistant 文本消息、用于初始化工具使用历史的函数调用，或函数调用输出。

• input_audio_buffer.clear— 清除输入音频缓冲区。使用它可以丢弃任何待处理的音频数据而不提交它。

• conversation.item.delete— 按 ID 删除对话项目。服务器通过 `conversation.item.deleted` 事件确认删除。

• conversation.item.truncate— 截断先前的助手音频消息项。在指定时长后删除音频和转录内容，仅保留截至该时间点的内容。服务器通过 `conversation.item.truncated` 事件确认。

• response.create— 请求服务器创建新的助手响应。使用服务器端 VAD 时会自动处理。

• response.cancel— 取消正在进行的响应。在 VAD 模式下，中断是自动的 - 使用此功能可在非 VAD 模式下手动取消。

服务器消息

• session.created— 通过 WebSocket 连接自动发送。包含会话配置。

• conversation.created— 连接时的第一条消息。通知客户端对话会话已创建。

• session.updated— 确认客户端的 session.update 消息，表明会话已配置。

• input_audio_buffer.speech_started— 通知服务器的 VAD 检测到语音开始。仅适用于 server_vad 回合检测。

• input_audio_buffer.speech_stopped— 通知服务器的 VAD 检测到语音结束。仅适用于 server_vad 回合检测。

• input_audio_buffer.committed— 输入音频缓冲区已作为用户消息提交。

• input_audio_buffer.timeout_triggered— `turn_detection.idle_timeout_ms` 空闲计时器已触发：助手完成响应后，在配置的时长内未检测到用户语音。服务器会提交一个静默的用户轮次并生成主动问候。

• input_audio_buffer.cleared— 确认输入音频缓冲区已被清除。

• conversation.item.deleted— 确认对话项目已被删除。

• conversation.item.added— 新的用户或助手消息已添加到对话历史中。

• conversation.item.truncated— 确认对话项目已被截断。响应 `conversation.item.truncate` 客户端事件而发送。

• conversation.item.input_audio_transcription.completed— 用户输入的音频转录已完成。

• conversation.item.input_audio_transcription.updated— 用户音频输入的流转录更新。当用户说话时发出，提供最终 `completed` 事件之前迄今为止的累积记录。请注意，这是累积的转录本，可能对之前更新的转录本进行了修正——这与转录本增量不同。仅当会话配置中的 `audio.input.transcription.model` 设置为 `grok-transcribe` 时发出。对于显示实时字幕很有用。

• input_audio_buffer.dtmf_event_received— 在 SIP 会话中检测到 DTMF 音（电话按键）。仅限 SIP，不会在直接 WebSocket 连接上发出。数字会在服务器端缓冲，并在按下 `#` 键、空闲 2.5 秒或用户开始说话时作为文本消息发送给模型。

• response.created— 新的助手响应轮次正在进行中。本轮的音频增量共享同一个 response_id。

• response.output_item.added— 消息历史中新增了一个助手响应项。

• response.output_item.done— 输出项已完成。

• response.content_part.added— 内容部分从输出项开始。

• response.content_part.done— 内容部分结束。

• response.output_audio_transcript.delta— 助手音频响应的流式文本转录增量。

• response.output_audio_transcript.done— 本次助手轮次的音频转录已生成完毕。

• response.output_audio.delta— 助手响应的 Base64 编码音频流式增量。

• response.output_audio.done— 本次助手轮次的音频已生成完毕。

• response.text.delta— 文本模式输出增量（使用文本模式时）。

• response.output_text.delta— 使用 OpenAI GA 事件名称的文本模式输出增量。功能与 `response.text.delta` 相同。客户端应处理这两个事件名称以获得最大兼容性。

• response.function_call_arguments.delta— 流式传输函数调用参数。

• response.function_call_arguments.done— 已通过完整参数触发函数调用。你的代码应执行该函数，并通过 `conversation.item.create` 返回类型为 `function_call_output` 的结果。

• mcp_list_tools.in_progress— MCP 工具发现已开始。

• mcp_list_tools.completed— MCP 工具发现成功。

• mcp_list_tools.failed— MCP 工具发现失败。

• response.mcp_call_arguments.delta— MCP 调用参数流式传输。

• response.mcp_call_arguments.done— MCP 调用参数最终确定。

• response.mcp_call.in_progress— MCP 服务器 HTTP 调用开始。

• response.mcp_call.completed— MCP 工具执行成功。

• response.mcp_call.failed— MCP 工具执行失败。

• response.done— 助手响应已完成。在所有音频和转录增量之后发送；客户端随后可添加新的对话项。

• error— 发生错误时发送。包含错误代码和消息。大多数错误都是可恢复的并且会话保持打开状态。

消息流示例

1. session.created (server)

2. conversation.created (server)

3. session.update (client)

4. session.updated (server)

5. conversation.item.create (client)

6. conversation.item.added (server)

7. response.create (client)

8. response.created (server)

9. response.output_item.added (server)

10. response.content_part.added (server)

11. response.output_audio.delta (server)

12. response.output_audio_transcript.delta (server)

13. response.output_audio.done (server)

14. response.output_audio_transcript.done (server)

15. response.content_part.done (server)

16. response.output_item.done (server)

17. response.done (server)

{
  "target_uri": "sip:agent@example.com"
}

{}

No parameters.

{}

tmpfile=$(mktemp /tmp/tts-output-XXXXXX.mp3)
trap 'rm -f "$tmpfile"' EXIT

http_code=$(curl -s -o "$tmpfile" -w "%{http_code}" \
  https://api.x.ai/v1/tts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "text": "Hello, this is a text-to-speech test from xAI.",
    "voice_id": "eve",
    "language": "en"
  }')

if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
  file_size=$(wc -c < "$tmpfile" | tr -d ' ')
  echo "{\"status\": $http_code, \"audio_bytes\": $file_size}"
else
  cat "$tmpfile"
  exit 1
fi

const response = await fetch("https://api.x.ai/v1/tts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Hello, this is a text-to-speech test from xAI.",
    voice_id: "eve",
    language: "en",
  }),
});

if (response.ok) {
  const audioBuffer = await response.arrayBuffer();
  console.log(
    JSON.stringify(
      {
        status: response.status,
        audio_bytes: audioBuffer.byteLength,
        content_type: response.headers.get("content-type") || "",
      },
      null,
      2,
    ),
  );
} else {
  const errorText = await response.text();
  console.error(errorText);
  process.exit(1);
}

import json
import os

import requests

response = requests.post(
    "https://api.x.ai/v1/tts",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "text": "Hello, this is a text-to-speech test from xAI.",
        "voice_id": "eve",
        "language": "en",
    },
)

if response.ok:
    print(
        json.dumps(
            {
                "status": response.status_code,
                "audio_bytes": len(response.content),
                "content_type": response.headers.get("Content-Type", ""),
            },
            indent=2,
        )
    )
else:
    print(response.text)
    raise SystemExit(1)

{
  "text": "Hello, this is a text-to-speech test from xAI.",
  "voice_id": "eve",
  "language": "en",
  "output_format": {
    "codec": "mp3",
    "sample_rate": 24000,
    "bit_rate": 128000
  }
}

{
  "status": 200,
  "audio_bytes": 62637
}

文本转语音 - 流媒体

WebSocket 端点：wss://api.x.ai/v1/tts

通过 WebSocket 双向流式传输文本到语音。增量发送文本并实时接收音频块。与批处理 POST 端点共享 `/v1/tts` 路径 - 带有 `Upgrade: websocket` 的 GET 会激活流模式。配置是在连接时通过查询参数完成的。支持多话语：在 `audio.done` 之后，在同一连接上发送另一个 `text.delta` 消息流。

完整的 Schema 和示例：/tts-streaming.ws.json

查询参数

• voice（string, optional, default: eve）— 语音标识符。使用 `GET /v1/tts/voices` 中的内置语音（例如 `eve`、`ara`）或自定义语音 ID。

• language（string, required）— BCP-47 语言代码（例如 `en`、`zh`、`pt-BR`）或 `auto` 用于自动语言检测。不区分大小写。

• codec（string, optional, default: mp3）— 输出的音频编解码器。

• sample_rate（integer, optional, default: 24000）— 采样率（以 Hz 为单位）。

• bit_rate（integer, optional, default: 128000）— 比特率（以 bps 为单位）。仅当 `codec` 为 `mp3` 时适​​用。

• optimize_streaming_latency（integer, optional, default: 0）— 延迟优化级别。 `0`（默认）：无优化 — 最佳音频质量。 `1`：减小第一个块的大小，以缩短首次音频的时间，并在块边界处进行较小的质量权衡。

• speed（number, optional, default: 1.0）— 语音速度倍增器。 `1.0` 是正常速度。低于 `1.0` 的值会减慢语音速度，高于 `1.0` 的值会加快语音速度。范围：`0.7` 到 `1.5`。

• text_normalization（boolean, optional, default: false）— 在合成前启用文本规范化。启用后，模型会在生成音频前将书写形式的文本（例如数字、缩写和符号）规范化为口语形式。

• with_timestamps（boolean, optional, default: false）— 返回每个 `audio.delta` 事件的每个字符计时元数据。当`true`时，每个`audio.delta`都携带`audio_timestamps`。

客户端消息

• text.delta — 发送一段待合成文本。文本按增量处理，缓冲了足够文本后即开始生成音频。每个增量最多 60,000 个字符。

• text.done— 表示该话语的所有文本均已发送。服务器将完成音频生成并发送`audio.done`。收到 `audio.done` 后，您可以使用另一个 `text.delta` 开始新的话语。

服务器消息

• audio.delta— 一块 Base64 编码的音频数据。解码并附加到音频缓冲区或直接通过管道播放。该格式与查询参数中指定的 `codec` 和 `sample_rate` 匹配。当使用 `with_timestamps=true` 打开连接时，该事件还为该块内的字符携带 `audio_timestamps` 和 `audio_duration` 。

• audio.done— 该话语的音频生成已完成。连接对于多话语保持打开状态 - 发送另一个 `text.delta` 以开始新的合成，或关闭连接。

• error— 合成过程中发生错误。在此消息之后连接可能会关闭。

消息流示例

1. text.delta (client)

2. text.delta (client)

3. text.done (client)

4. audio.delta (server)

5. audio.delta (server)

6. audio.delta (server)

7. audio.done (server)

curl -s https://api.x.ai/v1/tts/voices \
  -H "Authorization: Bearer $XAI_API_KEY"

const response = await fetch("https://api.x.ai/v1/tts/voices", {
  headers: {
    Authorization: `Bearer ${process.env.XAI_API_KEY}`,
  },
});

const data = await response.json();
console.log(JSON.stringify(data, null, 2));

import json
import os

import requests

response = requests.get(
    "https://api.x.ai/v1/tts/voices",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
    },
)

print(json.dumps(response.json(), indent=2))

No parameters.

{
  "voices": [
    {
      "voice_id": "ara",
      "name": "Ara",
      "language": "multilingual"
    },
    {
      "voice_id": "eve",
      "name": "Eve",
      "language": "multilingual"
    },
    {
      "voice_id": "leo",
      "name": "Leo",
      "language": "multilingual"
    },
    {
      "voice_id": "rex",
      "name": "Rex",
      "language": "multilingual"
    },
    {
      "voice_id": "sal",
      "name": "Sal",
      "language": "multilingual"
    }
  ]
}

curl -s https://api.x.ai/v1/tts/voices/eve \
  -H "Authorization: Bearer $XAI_API_KEY"

const voiceId = "eve";

const response = await fetch(`https://api.x.ai/v1/tts/voices/${voiceId}`, {
  headers: {
    Authorization: `Bearer ${process.env.XAI_API_KEY}`,
  },
});

const data = await response.json();
console.log(JSON.stringify(data, null, 2));

import json
import os

import requests

voice_id = "eve"

response = requests.get(
    f"https://api.x.ai/v1/tts/voices/{voice_id}",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
    },
)

print(json.dumps(response.json(), indent=2))

No parameters.

{
  "voice_id": "eve",
  "name": "Eve",
  "language": "multilingual"
}

No parameters.

{
  "text": "The balance is $167,983.15. That is $23.4 kilograms.",
  "language": "en",
  "duration": 8.4,
  "words": [
    {
      "text": "The",
      "start": 0,
      "end": 0.24,
      "confidence": 0.33
    },
    {
      "text": "balance",
      "start": 0.24,
      "end": 0.64,
      "confidence": 0.67
    },
    {
      "text": "is",
      "start": 0.64,
      "end": 0.88,
      "confidence": 0.41
    },
    {
      "text": "$167,983.15.",
      "start": 0.88,
      "end": 4.8,
      "confidence": 0.07
    },
    {
      "text": "That",
      "start": 6.16,
      "end": 6.48,
      "confidence": 0.29
    },
    {
      "text": "is",
      "start": 6.48,
      "end": 6.64,
      "confidence": 0.4
    },
    {
      "text": "$23.4",
      "start": 6.64,
      "end": 7.52,
      "confidence": 0.07
    },
    {
      "text": "kilograms.",
      "start": 7.76,
      "end": 8.4,
      "confidence": 0.09
    }
  ]
}

语音转文本 - 流式

WebSocket 端点：wss://api.x.ai/v1/stt

通过 WebSocket 实时流式进行语音转文本。以二进制帧发送原始音频，在音频处理过程中接收 JSON 转写事件。连接时通过查询参数配置。可使用 grok-voice-transcribe-1.0 或 grok-voice-transcribe-2.0；默认为 grok-voice-transcribe-2.0。

完整的 Schema 和示例：/stt-streaming.ws.json

查询参数

• sample_rate (integer, optional, default: 16000) — 音频采样率，单位为 Hz。支持的值：`8000`、`16000`、`22050`、`24000`、`44100`、`48000`。使用 `encoding=opus` 时忽略此参数——Opus 数据包与采样率无关。

• encoding (string, optional, default: pcm) — 音频编码格式。`pcm` — 有符号 16 位小端序（2 字节/采样）。`mulaw` — G.711 µ-law（1 字节/采样）。`alaw` — G.711 A-law（1 字节/采样）。`opus` — 原始 Opus 数据包，每个二进制 WebSocket 帧一个数据包，仅支持单声道。

• interim_results（boolean, optional, default: false）— 当 `true` 时，服务器在处理音频时大约每 500 毫秒发出部分转录事件 (`is_final=false`)。当 `false` （默认）时，仅发送最终结果。

• endpointing (integer, optional, default: 400) — 服务器触发 `speech_final=true` 事件前的静音时长，单位为毫秒；该事件表示说话者已停止讲话。范围：0–5000。设为 `0` 表示无延迟（遇到任何 VAD 静音边界即触发）。默认：400ms。

• language（string, optional, default: ）— 语言代码（例如 `en`、`fr`、`de`、`ja`）。设置后，启用反向文本规范化 - 口头形式的数字、货币和单位将转换为其书面形式。

• model（string，可选，默认值：grok-voice-transcribe-2.0）— `grok-voice-transcribe-1.0` 或 `grok-voice-transcribe-2.0`。默认为 `grok-voice-transcribe-2.0`。

• multichannel (boolean, optional, default: false) — 为 `true` 时，对交错多声道音频启用分声道转录。要求 `channels` ≥ 2。不支持 `encoding=opus`。

• channels（integer, optional, default: 1）— 交错音频通道的数量。当 `multichannel=true` 时需要。最小值：2，最大值：8。

• diarize（boolean, optional, default: false）— 当 `true` 时，启用说话者二值化。 `transcript.partial` 和 `transcript.done` 事件中的单词包含标识检测到的说话者的 `speaker` 字段（integer）。

• keyterm（string（可重复），可选）- 转录偏向的关键术语（例如产品名称、专有名词）。对每个术语重复该参数（例如 `keyterm=Understand+The+Universe`）。最多 100 个术语，每个术语最多 50 个字符。

• filler_words（boolean, optional, default: false）— 当 `true` 时，填充词（例如 `uh`、`um`、`er`）包含在记录中。当 `false` （默认）时，填充词会自动从记录文本和 `words` 数组中删除。

• smart_turn（数字，可选）— 启用 Smart Turn 回合结束检测。设为介于 `0.0` 和 `1.0` 的置信度阈值。当模型的回合结束概率在 VAD 静音边界超过此阈值时，会立即触发 `speech_final`。置信度低于阈值时，会抑制 `speech_final` 并将事件降级为 `chunk_final`。启用 Smart Turn 后，每个 `transcript.partial` 事件都包含 `end_of_turn_confidence` 字段（0.0–1.0）。示例：`smart_turn=0.7`。

• smart_turn_timeout（integer, optional）— 即使 Smart Turn 模型预测说话人尚未结束，仍会在达到此最大静音时长（毫秒）后强制触发 `speech_final`。它充当安全网，防止会话在长时间静音时挂起。仅在启用 `smart_turn` 时适用。范围：1–5000。示例：`smart_turn_timeout=3000`。

• vad_threshold（number, optional, default: 0.08）— 语音活动门的语音概率阈值 (0.0–1.0)。得分低于阈值的块中的音频被视为非语音并跳过转录。较低的值转录较安静或较嘈杂的语音（例如窄带电话），但可能会产生背景噪音的虚假文本； `0` 完全禁用门。不影响端点或 `speech_final` 计时。默认值：`0.08`。

客户端消息

• Binary frame (audio) — 按 `encoding` 查询参数指定的编码，通过二进制 WebSocket 帧发送原始音频。音频应按实时节奏分块传输（例如每次 100 ms）。无需 base64 编码，直接发送原始字节。使用 `encoding=opus` 时，每个二进制帧必须且只能包含一个原始 Opus 数据包，绝不能拼接多个数据包或将一个包拆分到多个帧。无法解码的帧会触发 `error` 事件并关闭会话。

• finalize— 强制当前话语立即最终确定为 `speech_final`，无需等待 VAD 端点或智能转向。会话保持打开状态，以便您可以继续传输音频。接受 `finalize` 或 `Finalize` 作为类型值。当 `multichannel=true` 时，可选 `channel` （从 0 开始）将最终确定限制为该通道；省略 `channel` 来完成每个通道。

• audio.done— 发出所有音频已发送的信号。服务器刷新所有剩余的缓冲音频，发出最终转录事件，并发送 `transcript.done` 事件。连接在 `transcript.done` 之后关闭。

服务器消息

• transcript.created— 在建立 WebSocket 连接且服务器准备好接收音频后立即发送。 **发送音频之前等待此事件** — 服务器需要初始化其 ASR 后端。

• transcript.partial— 音频流一部分的转录结果。两个布尔字段传达状态：临时 (`is_final=false`) 表示文本可能仍会更改，块最终 (`is_final=true`, `speech_final=false`) 表示块已锁定，而话语最终 (`is_final=true`, `speech_final=true`) 表示说话者停止说话。

• transcript.done— `audio.done` 之后的最终转录文本。始终包含 `duration`。当 `multichannel=true` 时，每个通道各有一个；此事件后连接关闭。

• error — 会话期间发生错误。大多数错误（处理流水线失败、流超时、无法解码的音频帧）会关闭连接。只有客户端消息解析错误会保持连接。

消息流示例

1. transcript.created (server)

2. Binary frame (audio) (client)

3. Binary frame (audio) (client)

4. transcript.partial (server)

5. Binary frame (audio) (client)

6. transcript.partial (server)

7. Binary frame (audio) (client)

8. transcript.partial (server)

9. audio.done (client)

10. transcript.done (server)

curl -s https://api.x.ai/v1/custom-voices \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F "name=Friendly Narrator" \
  -F "language=en" \
  -F "gender=female" \
  -F "tone=warm" \
  -F "use_case=narration" \
  -F "file=@reference.wav;type=audio/wav"

import fs from 'fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('reference.wav')]), 'reference.wav');
form.append('name', 'Friendly Narrator');
form.append('language', 'en');
form.append('gender', 'female');
form.append('tone', 'warm');
form.append('use_case', 'narration');

const response = await fetch('https://api.x.ai/v1/custom-voices', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.XAI_API_KEY}` },
  body: form,
});

console.log(JSON.stringify(await response.json(), null, 2));

import json
import os

import requests

with open("reference.wav", "rb") as f:
    response = requests.post(
        "https://api.x.ai/v1/custom-voices",
        headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
        files={"file": ("reference.wav", f, "audio/wav")},
        data={
            "name": "Friendly Narrator",
            "language": "en",
            "gender": "female",
            "tone": "warm",
            "use_case": "narration",
        },
    )

print(json.dumps(response.json(), indent=2))

{
  "file": "<binary audio file, e.g. reference.wav>",
  "name": "Friendly Narrator",
  "description": "Warm, conversational tone for narration.",
  "gender": "female",
  "accent": "American",
  "age": "young",
  "language": "en",
  "use_case": "narration",
  "tone": "warm"
}

{
  "voice_id": "nlbqfwie",
  "name": "Friendly Narrator",
  "description": null,
  "gender": "female",
  "accent": null,
  "age": null,
  "language": "en",
  "use_case": "narration",
  "tone": "warm",
  "created_at": "2026-04-26T18:56:34.872993+00:00"
}

curl -s https://api.x.ai/v1/custom-voices \
  -H "Authorization: Bearer $XAI_API_KEY"

const response = await fetch('https://api.x.ai/v1/custom-voices', {
  headers: { Authorization: `Bearer ${process.env.XAI_API_KEY}` },
});

console.log(JSON.stringify(await response.json(), null, 2));

import json
import os

import requests

response = requests.get(
    "https://api.x.ai/v1/custom-voices",
    headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
)

print(json.dumps(response.json(), indent=2))

No parameters.

{
  "voices": [
    {
      "voice_id": "nlbqfwie",
      "name": "Friendly Narrator",
      "description": "Warm, conversational tone for narration.",
      "gender": "female",
      "accent": "American",
      "age": "young",
      "language": "en",
      "use_case": "narration",
      "tone": "warm",
      "created_at": "2026-04-26T18:56:34.872993+00:00"
    }
  ],
  "pagination_token": null
}

curl -s https://api.x.ai/v1/custom-voices/nlbqfwie \
  -H "Authorization: Bearer $XAI_API_KEY"

const response = await fetch('https://api.x.ai/v1/custom-voices/nlbqfwie', {
  headers: { Authorization: `Bearer ${process.env.XAI_API_KEY}` },
});

console.log(JSON.stringify(await response.json(), null, 2));

import json
import os

import requests

response = requests.get(
    "https://api.x.ai/v1/custom-voices/nlbqfwie",
    headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
)

print(json.dumps(response.json(), indent=2))

No parameters.

{
  "voice_id": "nlbqfwie",
  "name": "Friendly Narrator",
  "description": "Warm, conversational tone for narration.",
  "gender": "female",
  "accent": "American",
  "age": "young",
  "language": "en",
  "use_case": "narration",
  "tone": "warm",
  "created_at": "2026-04-26T18:56:34.872993+00:00"
}

curl -s -X PATCH https://api.x.ai/v1/custom-voices/nlbqfwie \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated after a tuning pass.",
    "tone": "calm"
  }'

const response = await fetch('https://api.x.ai/v1/custom-voices/nlbqfwie', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    description: 'Updated after a tuning pass.',
    tone: 'calm',
  }),
});

console.log(JSON.stringify(await response.json(), null, 2));

import json
import os

import requests

response = requests.patch(
    "https://api.x.ai/v1/custom-voices/nlbqfwie",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "description": "Updated after a tuning pass.",
        "tone": "calm",
    },
)

print(json.dumps(response.json(), indent=2))

{
  "description": "Updated description after a tuning pass.",
  "tone": "calm"
}

{
  "voice_id": "nlbqfwie",
  "name": "Friendly Narrator",
  "description": "Updated after a tuning pass.",
  "gender": "female",
  "accent": "American",
  "age": "young",
  "language": "en",
  "use_case": "narration",
  "tone": "calm",
  "created_at": "2026-04-26T18:56:34.872993+00:00"
}

curl -s -X DELETE https://api.x.ai/v1/custom-voices/nlbqfwie \
  -H "Authorization: Bearer $XAI_API_KEY"

const response = await fetch('https://api.x.ai/v1/custom-voices/nlbqfwie', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.XAI_API_KEY}` },
});

console.log(JSON.stringify(await response.json(), null, 2));

import json
import os

import requests

response = requests.delete(
    "https://api.x.ai/v1/custom-voices/nlbqfwie",
    headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
)

print(json.dumps(response.json(), indent=2))

No parameters.

{
  "deleted": true
}

curl -s https://api.x.ai/v1/custom-voices/nlbqfwie/audio \
  -H "Authorization: Bearer $XAI_API_KEY" \
  --output reference.wav

const response = await fetch('https://api.x.ai/v1/custom-voices/nlbqfwie/audio', {
  headers: { Authorization: `Bearer ${process.env.XAI_API_KEY}` },
});

const audioBuffer = await response.arrayBuffer();
console.log(
  JSON.stringify(
    {
      status: response.status,
      audio_bytes: audioBuffer.byteLength,
      content_type: response.headers.get('content-type') || '',
    },
    null,
    2,
  ),
);

import json
import os

import requests

response = requests.get(
    "https://api.x.ai/v1/custom-voices/nlbqfwie/audio",
    headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
)

print(
    json.dumps(
        {
            "status": response.status_code,
            "audio_bytes": len(response.content),
            "content_type": response.headers.get("Content-Type", ""),
        },
        indent=2,
    )
)

No parameters.

{
  "status": 200,
  "audio_bytes": 1536044
}