实时音频（Realtime）

通过 WebSocket 或 WebRTC 与实时语音模型建立低延迟会话。适用于语音助手、边说边听交互。文本补全请使用 创建对话补全，不要对本页模型调用 /chat/completions。

支持模型示例：gpt-realtime-2.1、gpt-realtime-2.1-mini（以 获取模型 modality=audio 为准）。

---

Endpoint

Method	URL	说明
POST	{TRINITY_BASE_URL}/realtime/client_secrets	签发浏览器用临时凭证（WebRTC）
POST	{TRINITY_BASE_URL}/realtime/calls	WebRTC SDP 建连
WebSocket	{TRINITY_WS_BASE_URL}/realtime?model={model}	服务端 WebSocket 代理

---

Base URL

项	值
Base URL	https://api.trinitydesk.ai/v1
WebSocket	wss://api.trinitydesk.ai/v1
协议	HTTPS / WSS

export TRINITY_BASE_URL="https://api.trinitydesk.ai/v1"
export TRINITY_WS_BASE_URL="wss://api.trinitydesk.ai/v1"
export TRINITY_API_KEY="xh-..."

---

Headers

Header	必填	说明
Authorization	是	Bearer <TRINITY_API_KEY>
Content-Type	HTTP 时	application/json

WebSocket 也可在查询参数中携带 api_key=<TRINITY_API_KEY>（与 Header 二选一即可）。

---

请求示例

签发 client_secrets

curl -sS "${TRINITY_BASE_URL}/realtime/client_secrets" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -d '{
    "model": "gpt-realtime-2.1-mini",
    "session": {
      "type": "realtime",
      "output_modalities": ["text"]
    }
  }'

WebSocket（文本一轮）

连接：

${TRINITY_WS_BASE_URL}/realtime?model=gpt-realtime-2.1-mini&api_key=${TRINITY_API_KEY}

连接成功后可发送：

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [{ "type": "input_text", "text": "Say hello in one short sentence." }]
  }
}

{ "type": "response.create" }

服务端会转发 Realtime 事件流；计费以 response.done 中的 usage 为准。

---

请求体字段（client_secrets）

字段	类型	必填	说明
model	string	是	音频模型 ID
session	object	否	会话配置（如 type、output_modalities、instructions）

---

返回示例（client_secrets）

{
  "value": "ek_...",
  "expires_at": 1710000000,
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2.1-mini"
  }
}

字段名以上游返回为准；平台会保证会话侧 model 与选路部署一致。

---

Python 示例

import json
import os
import urllib.request
from urllib.parse import quote

import websocket  # pip install websocket-client

BASE = os.environ.get("TRINITY_BASE_URL", "https://api.trinitydesk.ai/v1")
KEY = os.environ["TRINITY_API_KEY"]
MODEL = "gpt-realtime-2.1-mini"

body = json.dumps({
    "model": MODEL,
    "session": {"type": "realtime", "output_modalities": ["text"]},
}).encode()
req = urllib.request.Request(
    f"{BASE}/realtime/client_secrets",
    data=body,
    headers={
        "Authorization": f"Bearer {KEY}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(req, timeout=30) as resp:
    print("client_secrets", resp.status, resp.read()[:200])

ws_url = (
    BASE.replace("https://", "wss://").replace("http://", "ws://")
    + f"/realtime?model={quote(MODEL)}&api_key={quote(KEY)}"
)
ws = websocket.create_connection(ws_url, timeout=60)
print(ws.recv()[:200])
ws.send(json.dumps({
    "type": "conversation.item.create",
    "item": {
        "type": "message",
        "role": "user",
        "content": [{"type": "input_text", "text": "Hi"}],
    },
}))
ws.send(json.dumps({"type": "response.create"}))
for _ in range(20):
    raw = ws.recv()
    ev = json.loads(raw)
    print(ev.get("type"))
    if ev.get("type") == "response.done":
        break
ws.close()

---

相关

• 获取模型（modality=audio）
• 获取价目
• 错误与调试