临时 token 为客户端应用提供安全、短时有效的身份验证。从浏览器或移动应用连接 Speech to Speech API 时请使用临时 token，以避免暴露 API key。

工作原理

你的 服务器 使用 API key 向 xAI 请求临时 token
服务器将临时 token 传递给 客户端
该 客户端 使用临时 token 验证 WebSocket 连接
token 会在配置的时长后自动过期

创建临时 token

需要设置一个服务器 endpoint，从 xAI 获取临时 token。临时 token 会为持有者授予范围受限的资源访问权限。

Endpoint： POST https://api.x.ai/v1/realtime/client_secrets

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

# Note: Does not support "session" or "expires_after.anchor" fields

# Example ephemeral token endpoint with FastAPI

import os
import httpx
from fastapi import FastAPI

app = FastAPI()
SESSION_REQUEST_URL = "https://api.x.ai/v1/realtime/client_secrets"
XAI_API_KEY = os.getenv("XAI_API_KEY")

@app.post("/session")
async def get_ephemeral_token():
    # Send request to xAI endpoint to retrieve the ephemeral token
    async with httpx.AsyncClient() as client:
        response = await client.post(
            url=SESSION_REQUEST_URL,
            headers={
                "Authorization": f"Bearer {XAI_API_KEY}",
                "Content-Type": "application/json",
            },
            json={"expires_after": {"seconds": 300}},
        )

    # Return the response body from xAI with ephemeral token
    return response.json()

// Example ephemeral token endpoint with Express

import express from 'express';

const app = express();
const SESSION_REQUEST_URL = "https://api.x.ai/v1/realtime/client_secrets";

app.use(express.json());

app.post("/session", async (req, res) => {
  const r = await fetch(SESSION_REQUEST_URL, {
    method: "POST",
    headers: {
      Authorization: \`Bearer \${process.env.XAI_API_KEY}\`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      expires_after: { seconds: 300 }
    }),
  });

  const data = await r.json();
  res.json(data);
});

app.listen(8081);

使用临时 token

临时 token 的使用方式与 API key 相同：

import os
import websockets

base_url = "wss://api.x.ai/v1/realtime?model=grok-voice-latest"

# Connect with API key in Authorization header
async with websockets.connect(
    uri=base_url,
    ssl=True,
    additional_headers={"Authorization": f"Bearer {OBTAINED_EPHEMERAL_TOKEN}"}
) as websocket:
    # WebSocket connection is now authenticated
    pass

import WebSocket from "ws";

const baseUrl = "wss://api.x.ai/v1/realtime?model=grok-voice-latest";

// Connect with API key in Authorization header
const ws = new WebSocket(baseUrl, {
  headers: {
    Authorization: "Bearer " + OBTAINED_EPHEMERAL_TOKEN,
    "Content-Type": "application/json",
  },
});

ws.on("open", () => {
  console.log("Connected with ephemeral token authentication");
});

浏览器 WebSocket 身份验证

如果需要从浏览器发送临时 token，可以将带有前缀 xai-client-secret. 的临时 token 添加到 sec-websocket-protocol header：

new WebSocket("wss://api.x.ai/v1/realtime", [\`xai-client-secret.\${OBTAINED_EPHEMERAL_TOKEN}\`]);

最后更新：2026 年 7 月 21 日