> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime API — 实时语音对话

> 通过 WebSocket 进行实时语音对话，支持 OpenAI 和 Azure 后端。

Realtime API 允许你通过 WebSocket 连接与模型进行低延迟、双向的语音和文本对话。无需发送离散的 HTTP 请求，你打开一个持久连接，双向交换事件消息——发送音频或文本输入，接收流式生成的音频或文本响应。

Anyone 的 Realtime 端点兼容 OpenAI Realtime API 格式，也支持 Azure OpenAI Realtime。连接前需要配置一个支持 Realtime 的渠道（OpenAI 或 Azure OpenAI）。

<Note>
  Realtime 需要配置支持实时对话的服务商渠道（OpenAI 或 Azure OpenAI）。如果 WebSocket 连接被拒绝，请联系你的 Anyone 管理员。
</Note>

***

## 连接

**端点：** `GET /v1/realtime`

将 HTTP GET 请求升级为 WebSocket 连接。可通过查询参数或 WebSocket 握手中的 `Authorization` 头传入 API key。

```
ws://api.anyone.ai/v1/realtime
```

TLS 加密实例：

```
wss://api.anyone.ai/v1/realtime
```

### 认证

通过以下方式传入 API key：

* **查询参数：** `?token=YOUR_TOKEN`
* **Authorization 头：** `Authorization: Bearer YOUR_TOKEN`（在 HTTP 升级握手时设置）

***

## 事件类型

连接后，双方交换 JSON 事件消息。每条消息包含 `type` 字段标识其用途。以下是核心事件类型。

### 客户端 → 服务端

| 事件类型                        | 说明                          |
| --------------------------- | --------------------------- |
| `session.update`            | 配置会话参数，如语音、音频格式、工具和指令。      |
| `input_audio_buffer.append` | 向模型的输入缓冲区发送 base64 编码的音频数据。 |
| `conversation.item.create`  | 向对话中添加一条文本消息。               |
| `response.create`           | 提示模型基于当前对话和缓冲区生成响应。         |

### 服务端 → 客户端

| 事件类型                                     | 说明                               |
| ---------------------------------------- | -------------------------------- |
| `session.created`                        | 连接后立即发送，确认会话已就绪。                 |
| `session.updated`                        | 确认 `session.update` 已生效。         |
| `response.audio.delta`                   | 模型响应中的一块 base64 编码音频。            |
| `response.audio_transcript.delta`        | 模型音频输出的文本转录片段。                   |
| `response.function_call_arguments.delta` | 流式 function calling 参数（模型调用工具时）。 |
| `response.function_call_arguments.done`  | function calling 参数发送完成。         |
| `response.done`                          | 模型完成响应生成。包含用量信息。                 |
| `conversation.item.created`              | 确认对话项已添加。                        |
| `error`                                  | 发生错误。包含错误对象及消息和代码。               |

***

## 会话配置

连接后，发送 `session.update` 事件配置会话：

<ParamField body="modalities" type="string[]">
  启用的交互模式。例如 `["text", "audio"]`。
</ParamField>

<ParamField body="instructions" type="string">
  系统级指令，引导模型在整个会话中的行为。
</ParamField>

<ParamField body="voice" type="string">
  音频输出使用的语音。例如 `alloy`、`echo`、`nova` 或 `shimmer`。
</ParamField>

<ParamField body="input_audio_format" type="string">
  你发送的音频格式。例如 `pcm16`、`g711_ulaw` 或 `g711_alaw`。
</ParamField>

<ParamField body="output_audio_format" type="string">
  模型返回的音频格式。例如 `pcm16`。
</ParamField>

<ParamField body="input_audio_transcription" type="object">
  音频输入转录配置。

  <Expandable title="属性">
    <ResponseField name="model" type="string">
      转录模型，例如 `whisper-1`。
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="turn_detection" type="object | null">
  控制服务端如何检测音频输入的轮次结束。设为 `null` 禁用自动检测，手动管理。
</ParamField>

<ParamField body="tools" type="object[]">
  会话中模型可用的工具列表，遵循 OpenAI function calling schema。
</ParamField>

<ParamField body="tool_choice" type="string">
  控制模型何时使用工具。`auto`、`none` 或指定工具名。
</ParamField>

<ParamField body="temperature" type="number">
  模型的采样温度。默认 `0.8`。
</ParamField>

***

## 用量统计

模型完成响应后，`response.done` 事件包含 `usage` 对象：

<ResponseField name="total_tokens" type="integer">此轮响应消耗的总 token 数。</ResponseField>
<ResponseField name="input_tokens" type="integer">输入中的 token 数（音频 + 文本）。</ResponseField>
<ResponseField name="output_tokens" type="integer">模型输出中的 token 数（音频 + 文本）。</ResponseField>
<ResponseField name="input_token_details" type="object">输入 token 类型明细（如缓存、音频）。</ResponseField>
<ResponseField name="output_token_details" type="object">输出 token 类型明细（如音频、文本）。</ResponseField>

***

## 示例

以下 JavaScript 示例连接 Realtime 端点、配置会话并记录收到的事件。

```javascript javascript theme={null}
const ws = new WebSocket(
  "wss://api.anyone.ai/v1/realtime?token=YOUR_TOKEN"
);

ws.addEventListener("open", () => {
  // Configure the session
  ws.send(
    JSON.stringify({
      type: "session.update",
      session: {
        modalities: ["text", "audio"],
        instructions: "You are a helpful assistant. Respond concisely.",
        voice: "alloy",
        input_audio_format: "pcm16",
        output_audio_format: "pcm16",
        temperature: 0.8,
      },
    })
  );

  // Send a text message
  ws.send(
    JSON.stringify({
      type: "conversation.item.create",
      item: {
        type: "message",
        role: "user",
        content: [{ type: "input_text", text: "Hello, how are you?" }],
      },
    })
  );

  // Ask the model to respond
  ws.send(JSON.stringify({ type: "response.create" }));
});

ws.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.type, msg);
});

ws.addEventListener("error", (err) => {
  console.error("WebSocket error", err);
});
```