# 建立 WebSocket 实时语音连接

> 音频生成

建立 WebSocket 连接进行实时语音交互。

**端点 URL 格式：**
```
wss://{endpoint}/v1/realtime?model={model_name}
```

**示例：**
```
wss://api.modelverse.cn/v1/realtime?model=gpt-realtime-2
```

**认证方式：**
```http
Authorization: Bearer {api_key}
```

**连接流程：**
1. 建立 WebSocket 连接，携带 model 参数和 Authorization header
2. 等待服务端返回 `session.created` 事件
3. 发送 `session.update` 配置会话参数
4. 开始发送音频数据

---

## Client Events（客户端发送）

通过 WebSocket 连接发送以下 JSON 事件：

### 1. session.update

**适用模型：** 对话模型、翻译模型、转录模型（三种模型都支持）

更新会话配置。三种模型的配置有所不同：

**对话模型配置：**
- `session.type`: "realtime"
- `session.instructions`: 系统提示词
- `session.voice`: 音色 (alloy/echo/fable/onyx/shimmer)
- `session.output_modalities`: ["audio"] 表示输出音频

**翻译模型配置：**
- 不需要 `session.type` 字段
- `session.audio.input.transcription`: 转录配置
- `session.audio.input.noise_reduction`: 降噪配置
- `session.audio.output.language`: 目标语言

**转录模型配置：**
- `session.type`: "transcription"
- `session.audio.input.transcription`: 转录配置

**请求示例：**
```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "你是一个有用的助手",
    "voice": "alloy",
    "output_modalities": ["audio"],
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "turn_detection": null
      },
      "output": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "voice": "alloy"
      }
    }
  }
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "session.update" |
| session | object | 会话配置对象 |
| session.type | string | 会话类型：realtime/transcription |
| session.instructions | string | 系统提示词（对话模型） |
| session.voice | string | 音色：alloy/echo/fable/onyx/shimmer |
| session.output_modalities | array | 输出模态，["audio"] 表示输出音频 |
| session.audio | object | 音频配置 |

---

### 2. input_audio_buffer.append

**适用模型：** 对话模型、转录模型

发送音频数据（对话模型和转录模型使用）。

**音频格式要求：**
- 编码：PCM 16-bit
- 采样率：24000Hz
- 声道：单声道
- 传输：Base64 编码

**请求示例：**
```json
{
  "type": "input_audio_buffer.append",
  "event_id": "event_001",
  "audio": "//uQxAAAAAA..."
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "input_audio_buffer.append" |
| event_id | string | 事件唯一标识 |
| audio | string | Base64 编码的 PCM 音频数据 |

---

### 3. session.input_audio_buffer.append

**适用模型：** 翻译模型（专用）

发送音频数据（**翻译模型专用**）。

**注意：** 翻译模型使用此事件，而非 `input_audio_buffer.append`。

**请求示例：**
```json
{
  "type": "session.input_audio_buffer.append",
  "audio": "//uQxAAAAAA..."
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "session.input_audio_buffer.append" |
| audio | string | Base64 编码的 PCM 音频数据 |

---

### 4. input_audio_buffer.commit

**适用模型：** 对话模型、转录模型

提交音频缓冲区，通知服务端可以开始处理已发送的音频数据。

**使用场景：**
- 对话模型：提交后等待 AI 回复
- 转录模型：提交后等待转录结果

**请求示例：**
```json
{
  "type": "input_audio_buffer.commit",
  "event_id": "event_002"
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "input_audio_buffer.commit" |
| event_id | string | 事件唯一标识 |

---

### 5. response.create

**适用模型：** 对话模型（专用）

请求 AI 生成回复。**仅对话模型使用**。

**触发时机：**
- 用户说完一段话后发送
- 或者在 `input_audio_buffer.commit` 后自动触发

**请求示例：**
```json
{
  "type": "response.create"
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "response.create" |

---

## Server Events（服务端返回）

通过 WebSocket 连接接收以下 JSON 事件：

### 1. session.created

**适用模型：** 对话模型、翻译模型、转录模型（三种模型都支持）

表示 WebSocket 连接成功，会话已创建。

**触发时机：**
- 客户端成功建立 WebSocket 连接后立即返回

**后续操作：**
- 客户端应等待此事件后，再发送 `session.update` 配置会话

**响应示例：**
```json
{
  "type": "session.created",
  "event_id": "evt_001",
  "session": {
    "id": "sess_abc123",
    "model": "gpt-realtime-2",
    "instructions": "你是一个有用的助手"
  }
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "session.created" |
| event_id | string | 事件唯一标识 |
| session | object | 会话信息 |
| session.id | string | 会话 ID |
| session.model | string | 模型名称 |
| session.instructions | string | 系统提示词 |

---

### 2. response.output_audio.delta

**适用模型：** 对话模型

AI 生成的语音片段（Base64 编码的 PCM 音频）。

**特点：**
- 流式返回，多个 delta 片段组成完整语音
- 客户端需要按顺序播放
- 音频格式：PCM 16-bit, 24000Hz, 单声道

**响应示例：**
```json
{
  "type": "response.output_audio.delta",
  "delta": "//uQxAAAAAA..."
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "response.output_audio.delta" |
| delta | string | Base64 编码的 PCM 音频数据片段 |

---

### 3. response.output_audio_transcript.delta

**适用模型：** 对话模型

AI 语音对应的文字片段（实时字幕）。

**特点：**
- 流式返回，与音频片段同步
- 可用于显示实时字幕

**响应示例：**
```json
{
  "type": "response.output_audio_transcript.delta",
  "delta": "你好，我是"
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "response.output_audio_transcript.delta" |
| delta | string | 文字片段内容 |

---

### 4. response.done

**适用模型：** 对话模型

表示 AI 回复已完整生成。

**触发时机：**
- AI 语音全部发送完毕
- 客户端可以开始下一轮对话

**响应示例：**
```json
{
  "type": "response.done"
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "response.done" |

---

### 5. session.input_transcript.delta

**适用模型：** 翻译模型

翻译模型返回的源语言转录文字片段。

**使用场景：**
- 实时显示用户说话的源语言文字
- 与目标语言翻译同步显示

**响应示例：**
```json
{
  "type": "session.input_transcript.delta",
  "delta": "你好"
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "session.input_transcript.delta" |
| delta | string | 源语言转录文字片段 |

---

### 6. session.output_transcript.delta

**适用模型：** 翻译模型

翻译模型返回的目标语言翻译文字片段。

**使用场景：**
- 实时显示翻译后的目标语言文字

**响应示例：**
```json
{
  "type": "session.output_transcript.delta",
  "delta": "Hello"
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "session.output_transcript.delta" |
| delta | string | 目标语言翻译文字片段 |

---

### 7. session.output_audio.delta

**适用模型：** 翻译模型

翻译模型返回的翻译后语音片段（Base64 编码）。

**特点：**
- 流式返回翻译后的语音
- 音频格式：PCM 16-bit, 24000Hz, 单声道

**响应示例：**
```json
{
  "type": "session.output_audio.delta",
  "delta": "//uQxAAAAAA..."
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "session.output_audio.delta" |
| delta | string | Base64 编码的翻译后音频数据 |

---

### 8. conversation.item.input_audio_transcription.completed

**适用模型：** 转录模型

转录模型返回的最终转录结果。

**触发时机：**
- 用户说完一段话后
- 返回完整的转录文字

**响应示例：**
```json
{
  "type": "conversation.item.input_audio_transcription.completed",
  "transcript": "你好，这是一个转录测试"
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "conversation.item.input_audio_transcription.completed" |
| transcript | string | 转录完成的文字内容 |

---

### 9. error

**适用模型：** 对话模型、翻译模型、转录模型（三种模型都支持）

服务端返回的错误信息。

**常见错误：**
- 无效的模型名称
- 认证失败
- 音频格式错误
- 会话配置错误

**响应示例：**
```json
{
  "type": "error",
  "error": {
    "code": "invalid_model",
    "message": "Invalid model name"
  }
}
```

**字段说明：**
| 字段 | 类型 | 说明 |
|------|------|------|
| type | string | 固定值 "error" |
| error | object | 错误信息 |
| error.code | string | 错误代码 |
| error.message | string | 错误信息 |

## 请求地址

`GET https://api.modelverse.cn/`

## 请求参数

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| model | query | string | Yes | 模型名称，例如 gpt-realtime-2, gpt-realtime-translate, gpt-realtime-whisper |

## 响应

- **101** — WebSocket 连接成功建立
- **400** — 无效的模型参数
- **401** — 认证失败

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Modelverse GPT-Realtime 实时语音 API",
    "version": "1.0.0",
    "description": "Modelverse GPT-Realtime 实时语音模型 API，支持实时语音对话、翻译和转录功能。\n\n**模型列表：**\n| 模型类型 | 模型名称 |\n|---------|---------|\n| 对话模型 | gpt-realtime, gpt-realtime-1.5, gpt-realtime-2, gpt-realtime-2.1, gpt-realtime-2.1-mini |\n| 翻译模型 | gpt-realtime-translate |\n| 转录模型 | gpt-realtime-whisper |\n"
  },
  "servers": [
    {
      "url": "wss://api.modelverse.cn/v1/realtime",
      "description": "中国大陆节点，WebSocket 实时语音连接"
    },
    {
      "url": "wss://api-sg.umodelverse.ai/v1/realtime",
      "description": "新加坡节点，WebSocket 实时语音连接"
    },
    {
      "url": "wss://api-us-ca.umodelverse.ai/v1/realtime",
      "description": "美国洛杉矶节点，WebSocket 实时语音连接"
    },
    {
      "url": "wss://api-ge-fra.umodelverse.ai/v1/realtime",
      "description": "法兰克福节点，WebSocket 实时语音连接"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "connectRealtime",
        "summary": "建立 WebSocket 实时语音连接",
        "description": "建立 WebSocket 连接进行实时语音交互。\n\n**端点 URL 格式：**\n```\nwss://{endpoint}/v1/realtime?model={model_name}\n```\n\n**示例：**\n```\nwss://api.modelverse.cn/v1/realtime?model=gpt-realtime-2\n```\n\n**认证方式：**\n```http\nAuthorization: Bearer {api_key}\n```\n\n**连接流程：**\n1. 建立 WebSocket 连接，携带 model 参数和 Authorization header\n2. 等待服务端返回 `session.created` 事件\n3. 发送 `session.update` 配置会话参数\n4. 开始发送音频数据\n\n---\n\n## Client Events（客户端发送）\n\n通过 WebSocket 连接发送以下 JSON 事件：\n\n### 1. session.update\n\n**适用模型：** 对话模型、翻译模型、转录模型（三种模型都支持）\n\n更新会话配置。三种模型的配置有所不同：\n\n**对话模型配置：**\n- `session.type`: \"realtime\"\n- `session.instructions`: 系统提示词\n- `session.voice`: 音色 (alloy/echo/fable/onyx/shimmer)\n- `session.output_modalities`: [\"audio\"] 表示输出音频\n\n**翻译模型配置：**\n- 不需要 `session.type` 字段\n- `session.audio.input.transcription`: 转录配置\n- `session.audio.input.noise_reduction`: 降噪配置\n- `session.audio.output.language`: 目标语言\n\n**转录模型配置：**\n- `session.type`: \"transcription\"\n- `session.audio.input.transcription`: 转录配置\n\n**请求示例：**\n```json\n{\n  \"type\": \"session.update\",\n  \"session\": {\n    \"type\": \"realtime\",\n    \"instructions\": \"你是一个有用的助手\",\n    \"voice\": \"alloy\",\n    \"output_modalities\": [\"audio\"],\n    \"audio\": {\n      \"input\": {\n        \"format\": { \"type\": \"audio/pcm\", \"rate\": 24000 },\n        \"turn_detection\": null\n      },\n      \"output\": {\n        \"format\": { \"type\": \"audio/pcm\", \"rate\": 24000 },\n        \"voice\": \"alloy\"\n      }\n    }\n  }\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"session.update\" |\n| session | object | 会话配置对象 |\n| session.type | string | 会话类型：realtime/transcription |\n| session.instructions | string | 系统提示词（对话模型） |\n| session.voice | string | 音色：alloy/echo/fable/onyx/shimmer |\n| session.output_modalities | array | 输出模态，[\"audio\"] 表示输出音频 |\n| session.audio | object | 音频配置 |\n\n---\n\n### 2. input_audio_buffer.append\n\n**适用模型：** 对话模型、转录模型\n\n发送音频数据（对话模型和转录模型使用）。\n\n**音频格式要求：**\n- 编码：PCM 16-bit\n- 采样率：24000Hz\n- 声道：单声道\n- 传输：Base64 编码\n\n**请求示例：**\n```json\n{\n  \"type\": \"input_audio_buffer.append\",\n  \"event_id\": \"event_001\",\n  \"audio\": \"//uQxAAAAAA...\"\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"input_audio_buffer.append\" |\n| event_id | string | 事件唯一标识 |\n| audio | string | Base64 编码的 PCM 音频数据 |\n\n---\n\n### 3. session.input_audio_buffer.append\n\n**适用模型：** 翻译模型（专用）\n\n发送音频数据（**翻译模型专用**）。\n\n**注意：** 翻译模型使用此事件，而非 `input_audio_buffer.append`。\n\n**请求示例：**\n```json\n{\n  \"type\": \"session.input_audio_buffer.append\",\n  \"audio\": \"//uQxAAAAAA...\"\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"session.input_audio_buffer.append\" |\n| audio | string | Base64 编码的 PCM 音频数据 |\n\n---\n\n### 4. input_audio_buffer.commit\n\n**适用模型：** 对话模型、转录模型\n\n提交音频缓冲区，通知服务端可以开始处理已发送的音频数据。\n\n**使用场景：**\n- 对话模型：提交后等待 AI 回复\n- 转录模型：提交后等待转录结果\n\n**请求示例：**\n```json\n{\n  \"type\": \"input_audio_buffer.commit\",\n  \"event_id\": \"event_002\"\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"input_audio_buffer.commit\" |\n| event_id | string | 事件唯一标识 |\n\n---\n\n### 5. response.create\n\n**适用模型：** 对话模型（专用）\n\n请求 AI 生成回复。**仅对话模型使用**。\n\n**触发时机：**\n- 用户说完一段话后发送\n- 或者在 `input_audio_buffer.commit` 后自动触发\n\n**请求示例：**\n```json\n{\n  \"type\": \"response.create\"\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"response.create\" |\n\n---\n\n## Server Events（服务端返回）\n\n通过 WebSocket 连接接收以下 JSON 事件：\n\n### 1. session.created\n\n**适用模型：** 对话模型、翻译模型、转录模型（三种模型都支持）\n\n表示 WebSocket 连接成功，会话已创建。\n\n**触发时机：**\n- 客户端成功建立 WebSocket 连接后立即返回\n\n**后续操作：**\n- 客户端应等待此事件后，再发送 `session.update` 配置会话\n\n**响应示例：**\n```json\n{\n  \"type\": \"session.created\",\n  \"event_id\": \"evt_001\",\n  \"session\": {\n    \"id\": \"sess_abc123\",\n    \"model\": \"gpt-realtime-2\",\n    \"instructions\": \"你是一个有用的助手\"\n  }\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"session.created\" |\n| event_id | string | 事件唯一标识 |\n| session | object | 会话信息 |\n| session.id | string | 会话 ID |\n| session.model | string | 模型名称 |\n| session.instructions | string | 系统提示词 |\n\n---\n\n### 2. response.output_audio.delta\n\n**适用模型：** 对话模型\n\nAI 生成的语音片段（Base64 编码的 PCM 音频）。\n\n**特点：**\n- 流式返回，多个 delta 片段组成完整语音\n- 客户端需要按顺序播放\n- 音频格式：PCM 16-bit, 24000Hz, 单声道\n\n**响应示例：**\n```json\n{\n  \"type\": \"response.output_audio.delta\",\n  \"delta\": \"//uQxAAAAAA...\"\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"response.output_audio.delta\" |\n| delta | string | Base64 编码的 PCM 音频数据片段 |\n\n---\n\n### 3. response.output_audio_transcript.delta\n\n**适用模型：** 对话模型\n\nAI 语音对应的文字片段（实时字幕）。\n\n**特点：**\n- 流式返回，与音频片段同步\n- 可用于显示实时字幕\n\n**响应示例：**\n```json\n{\n  \"type\": \"response.output_audio_transcript.delta\",\n  \"delta\": \"你好，我是\"\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"response.output_audio_transcript.delta\" |\n| delta | string | 文字片段内容 |\n\n---\n\n### 4. response.done\n\n**适用模型：** 对话模型\n\n表示 AI 回复已完整生成。\n\n**触发时机：**\n- AI 语音全部发送完毕\n- 客户端可以开始下一轮对话\n\n**响应示例：**\n```json\n{\n  \"type\": \"response.done\"\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"response.done\" |\n\n---\n\n### 5. session.input_transcript.delta\n\n**适用模型：** 翻译模型\n\n翻译模型返回的源语言转录文字片段。\n\n**使用场景：**\n- 实时显示用户说话的源语言文字\n- 与目标语言翻译同步显示\n\n**响应示例：**\n```json\n{\n  \"type\": \"session.input_transcript.delta\",\n  \"delta\": \"你好\"\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"session.input_transcript.delta\" |\n| delta | string | 源语言转录文字片段 |\n\n---\n\n### 6. session.output_transcript.delta\n\n**适用模型：** 翻译模型\n\n翻译模型返回的目标语言翻译文字片段。\n\n**使用场景：**\n- 实时显示翻译后的目标语言文字\n\n**响应示例：**\n```json\n{\n  \"type\": \"session.output_transcript.delta\",\n  \"delta\": \"Hello\"\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"session.output_transcript.delta\" |\n| delta | string | 目标语言翻译文字片段 |\n\n---\n\n### 7. session.output_audio.delta\n\n**适用模型：** 翻译模型\n\n翻译模型返回的翻译后语音片段（Base64 编码）。\n\n**特点：**\n- 流式返回翻译后的语音\n- 音频格式：PCM 16-bit, 24000Hz, 单声道\n\n**响应示例：**\n```json\n{\n  \"type\": \"session.output_audio.delta\",\n  \"delta\": \"//uQxAAAAAA...\"\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"session.output_audio.delta\" |\n| delta | string | Base64 编码的翻译后音频数据 |\n\n---\n\n### 8. conversation.item.input_audio_transcription.completed\n\n**适用模型：** 转录模型\n\n转录模型返回的最终转录结果。\n\n**触发时机：**\n- 用户说完一段话后\n- 返回完整的转录文字\n\n**响应示例：**\n```json\n{\n  \"type\": \"conversation.item.input_audio_transcription.completed\",\n  \"transcript\": \"你好，这是一个转录测试\"\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"conversation.item.input_audio_transcription.completed\" |\n| transcript | string | 转录完成的文字内容 |\n\n---\n\n### 9. error\n\n**适用模型：** 对话模型、翻译模型、转录模型（三种模型都支持）\n\n服务端返回的错误信息。\n\n**常见错误：**\n- 无效的模型名称\n- 认证失败\n- 音频格式错误\n- 会话配置错误\n\n**响应示例：**\n```json\n{\n  \"type\": \"error\",\n  \"error\": {\n    \"code\": \"invalid_model\",\n    \"message\": \"Invalid model name\"\n  }\n}\n```\n\n**字段说明：**\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| type | string | 固定值 \"error\" |\n| error | object | 错误信息 |\n| error.code | string | 错误代码 |\n| error.message | string | 错误信息 |\n",
        "parameters": [
          {
            "name": "model",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "模型名称，例如 gpt-realtime-2, gpt-realtime-translate, gpt-realtime-whisper"
          }
        ],
        "responses": {
          "101": {
            "description": "WebSocket 连接成功建立"
          },
          "400": {
            "description": "无效的模型参数",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "认证失败",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "WebSocket 连接时在 HTTP Header 中携带"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "description": "错误响应",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
```