# GPT-Realtime 实时语音模型

本文档介绍 ModelVerse 平台 GPT-Realtime 系列实时语音模型的使用方法。

## 模型列表

| 模型类型 | 模型名称 | 说明 |
|---------|---------|------|
| **对话模型** | gpt-realtime, gpt-realtime-1.5, gpt-realtime-2, gpt-realtime-2.1, gpt-realtime-2.1-mini | 实时语音对话，支持语音输入和语音输出 |
| **翻译模型** | gpt-realtime-translate | 实时语音翻译，例如中文语音输入，英文语音输出 |
| **转录模型** | gpt-realtime-whisper | 实时语音转文字 |

---

## WebSocket 连接建立

### 端点 URL

```
wss://{endpoint}/v1/realtime?model={model_name}
```

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

### 认证方式

```http
Authorization: Bearer {api_key}
```

### 建立连接流程

```javascript
// JavaScript 示例
const ws = new WebSocket('wss://api.modelverse.cn/v1/realtime?model=gpt-realtime');

ws.onopen = () => console.log('连接建立');
ws.onmessage = (event) => handleMessage(JSON.parse(event.data));
```

```go
// Go 示例
headers := http.Header{}
headers.Set("Authorization", "Bearer "+token)
conn, _, err := websocket.DefaultDialer.Dial(wsURL, headers)
```

### 等待 session.created

连接成功后，服务端立即返回：

```json
{
  "type": "session.created",
  "event_id": "evt_xxx",
  "session": {
    "id": "sess_xxx",
    "model": "gpt-realtime-2",
    "instructions": ""
  }
}
```

---

## 对话模型（gpt-realtime 系列）

适用模型：gpt-realtime, gpt-realtime-1.5, gpt-realtime-2, gpt-realtime-2.1, gpt-realtime-2.1-mini

### session.update 配置

```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"
      }
    }
  }
}
```

**关键字段说明**：
- `session.type`: `"realtime"`（必需）
- `output_modalities`: `["audio"]` 表示输出音频
- `instructions`: 系统提示词
- `voice`: 音色（alloy/echo/fable/onyx/shimmer）

### 音频发送流程

**1. 发送音频（流式）**
```json
{
  "type": "input_audio_buffer.append",
  "event_id": "append_xxx",
  "audio": "<base64-encoded-pcm>"
}
```

**2. 结束录音（commit）**
```json
{
  "type": "input_audio_buffer.commit"
}
```

**3. 请求 AI 回复**
```json
{
  "type": "response.create"
}
```

### 服务端返回事件

| 事件类型 | 说明 |
|---------|------|
| `session.updated` | 配置更新成功 |
| `conversation.item.created` | 对话项创建 |
| `response.created` | 响应创建 |
| `response.output_audio.delta` | AI 语音片段（Base64） |
| `response.output_audio_transcript.delta` | AI 说的文字 |
| `response.done` | 响应完成 |
| `error` | 错误信息 |

---

## 翻译模型（gpt-realtime-translate）

**特点**：实时翻译，你说中文，AI 用英文语音回复。

### session.update 配置

**⚠️ 与对话模型完全不同！**

```json
{
  "type": "session.update",
  "session": {
    "audio": {
      "input": {
        "transcription": {
          "model": "gpt-realtime-whisper"
        },
        "noise_reduction": {
          "type": "near_field"
        }
      },
      "output": {
        "language": "en"
      }
    }
  }
}
```

**关键差异**：
- 没有 `type: "realtime"`
- 没有 `output_modalities`
- 没有 `instructions`
- 通过 `output.language` 指定目标语言

### 音频发送流程

**1. 发送音频（注意 session. 前缀）**
```json
{
  "type": "session.input_audio_buffer.append",
  "audio": "<base64-encoded-pcm>"
}
```

**2. 结束录音**

**⚠️ Translate 不需要 commit！**

翻译模型是流式自动处理，发送完音频即可，无需发送 `session.input_audio_buffer.commit`。

### 服务端返回事件

| 事件类型 | 说明 |
|---------|------|
| `session.updated` | 配置更新成功 |
| `session.input_transcript.delta` | 源语言转录（中文） |
| `session.output_transcript.delta` | 目标语言翻译（英文） |
| `session.output_audio.delta` | 翻译后的音频（Base64） |
| `session.input_transcript.done` | 源语言转录完成 |
| `session.output_transcript.done` | 译文完成 |
| `session.output_audio.done` | 语音播放完成 |
| `session.closed` | 会话关闭 |
| `error` | 错误信息 |

---

## 转录模型（gpt-realtime-whisper）

**特点**：语音识别，你说一句，返回文字（无音频输出）。

### session.update 配置

**⚠️ 与对话模型完全不同！**

```json
{
  "type": "session.update",
  "session": {
    "type": "transcription",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "turn_detection": null,
        "transcription": {
          "model": "gpt-realtime-whisper",
          "delay": "medium",
          "language": "zh"
        }
      }
    }
  }
}
```

**关键差异**：
- `type: "transcription"`（不是 realtime）
- 没有 `output` 配置（不返回音频）
- `transcription` 配置在 `input` 内部
- 支持 `delay` 和 `language` 参数

### 音频发送流程

**1. 发送音频**
```json
{
  "type": "input_audio_buffer.append",
  "event_id": "append_xxx",
  "audio": "<base64-encoded-pcm>"
}
```

**2. 结束录音（commit）**
```json
{
  "type": "input_audio_buffer.commit",
  "event_id": "commit_xxx"
}
```

**⚠️ 注意**：转录模型**不需要** `response.create`，commit 后自动返回转录结果！

### 服务端返回事件

| 事件类型 | 说明 |
|---------|------|
| `session.updated` | 配置更新成功 |
| `conversation.item.input_audio_transcription.completed` | 转录完成 |
| `conversation.item.created` | 对话项创建 |
| `error` | 错误信息 |

---

## 音频格式

### 输入音频格式

| 参数 | 值 |
|------|---|
| 编码 | PCM 16-bit |
| 采样率 | 24000 Hz |
| 声道 | 单声道 (1) |
| 传输 | Base64 编码 |

### 输出音频格式（对话和翻译模型）

| 参数 | 值 |
|------|---|
| 编码 | PCM 16-bit |
| 采样率 | 24000 Hz |
| 声道 | 单声道 (1) |
| 传输 | Base64 编码 |

---

## 关键差异总结

### 模型配置对比

| 配置项 | 对话模型 | 翻译模型 | 转录模型 |
|--------|---------|---------|---------|
| `session.type` | `"realtime"` | 无 | `"transcription"` |
| `output_modalities` | `["audio"]` | 无 | 无 |
| `instructions` | 有 | 无 | 无 |
| `audio.input.transcription` | 可选 | 有 | 有 |
| `audio.output` | 有 | `{"language": "en"}` | 无 |
| `audio.output.voice` | `"alloy"` | 无 | 无 |

### 音频事件对比

| 事件类型 | 对话模型 | 翻译模型 | 转录模型 |
|---------|---------|---------|---------|
| 音频发送 | `input_audio_buffer.append` | `session.input_audio_buffer.append` | `input_audio_buffer.append` |
| commit | `input_audio_buffer.commit` | **不需要** | `input_audio_buffer.commit` |
| 请求响应 | 需要 `response.create` | **不需要** | **不需要** |

---

## 附录：事件类型速查表

### 客户端发送事件

| 事件类型 | 适用模型 | 说明 |
|---------|---------|------|
| `session.update` | 全部 | 配置会话 |
| `input_audio_buffer.append` | 对话/转录 | 发送音频 |
| `session.input_audio_buffer.append` | 翻译 | 发送音频（带前缀） |
| `input_audio_buffer.commit` | 对话/转录 | 提交音频 |
| `response.create` | 对话 | 请求 AI 回复 |

### 服务端返回事件

| 事件类型 | 对话 | 翻译 | 转录 | 说明 |
|---------|------|------|------|------|
| `session.created` | ✅ | ✅ | ✅ | 会话已创建 |
| `session.updated` | ✅ | ✅ | ✅ | 配置已更新 |
| `response.output_audio.delta` | ✅ | ✅ | ❌ | AI 语音片段 |
| `response.output_audio_transcript.delta` | ✅ | ❌ | ❌ | AI 说的文字 |
| `response.done` | ✅ | ❌ | ❌ | 回复完成 |
| `session.input_transcript.delta` | ❌ | ✅ | ❌ | 原文转录 |
| `session.output_transcript.delta` | ❌ | ✅ | ❌ | 译文 |
| `session.output_audio.delta` | ❌ | ✅ | ❌ | 翻译语音 |
| `session.output_audio.done` | ❌ | ✅ | ❌ | 语音完成 |
| `conversation.item.input_audio_transcription.completed` | ❌ | ❌ | ✅ | 转录完成 |
| `error` | ✅ | ✅ | ✅ | 错误 |

---

## 参考文档

- [Azure OpenAI Realtime API event 参考](https://learn.microsoft.com/en-us/azure/foundry-classic/openai/realtime-audio-reference-ga#client-events)