Взаимодействие в реальном времени

OpenAI Realtime использует постоянное соединение и двунаправленные события для работы с текстом, аудио и вызовами функций в реальном времени. Клиент отправляет события сеанса, аудиобуфера, элементов диалога и управления ответами, а сервер непрерывно возвращает состояния сеанса, транскрипции, текст, аудио, аргументы функций и события ошибок.

Основной способ подключения на этой странице — WebSocket. При подключении замените MODEL_ID на ID модели, видимой текущему аккаунту и поддерживающей Realtime.

Типичные сценарии включают голосовой диалог в реальном времени, транскрипцию встреч и голосовых ассистентов, перевод и транскрипцию речи, интерактивную работу с кодом и серверные интеграции в реальном времени. Соединение может одновременно передавать текст и аудио, обрабатывая VAD, вызовы функций и обновления состояния через события.

Аутентификация и подключение

Аутентификация WebSocket

Серверное приложение устанавливает соединение WSS с помощью Bearer-ключа API и передаёт Header Realtime Beta в запросе рукопожатия.

Долгосрочный ключ API следует использовать только на доверенном сервере. Не добавляйте его в браузерный код, мобильный пакет или публичный репозиторий. Все соединения должны использовать HTTPS/WSS.

Временный токен

Перед подключением клиента доверенный сервер может создать временный токен со сроком действия в одну минуту, предназначенный только для одного соединения.

POST https://api.agtcloud.cn/v1/realtime/sessions
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "model": "MODEL_ID",
  "voice": "verse"
}

Процесс подключения

В основном процессе WebSocket сервер устанавливает соединение непосредственно с ключом API. После успешного рукопожатия по этому соединению отправляются клиентские события и принимаются серверные.

В процессе WebRTC клиент сначала запрашивает временный токен у сервера своего приложения, который создаёт его через интерфейс сеансов. Затем клиент создаёт SDP Offer, отправляет его на Endpoint Realtime и получает SDP Answer, после чего обменивается событиями JSON по каналу данных oai-events.

Примеры подключения WebSocket

Следующие примеры показывают Node.js, Python, отправку и получение событий. После подключения клиент отправляет события JSON, а сервер непрерывно возвращает результаты также в виде событий JSON.

import WebSocket from 'ws';

const ws = new WebSocket('wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID', {
  headers: {
    Authorization: 'Bearer your-api-key',
    'OpenAI-Beta': 'realtime=v1',
  },
});

ws.on('open', () => {
  console.log('Соединение с сервером установлено.');
});

ws.on('message', (message) => {
  console.log(JSON.parse(message.toString()));
});

Подключение WebRTC

Сейчас рекомендуется WebSocket. Перед использованием WebRTC проверьте его поддержку целевой моделью. Следующие примеры показывают базовую структуру подключения с временным токеном, SDP, аудиодорожкой и каналом данных.

async function init() {
  const tokenResponse = await fetch('/session');
  const data = await tokenResponse.json();
  const ephemeralKey = data.client_secret.value;

  const pc = new RTCPeerConnection();
  const audioElement = document.createElement('audio');
  audioElement.autoplay = true;
  pc.ontrack = (event) => {
    audioElement.srcObject = event.streams[0];
  };

  const mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });
  pc.addTrack(mediaStream.getTracks()[0]);

  const dataChannel = pc.createDataChannel('oai-events');
  dataChannel.addEventListener('message', (event) => {
    console.log(JSON.parse(event.data));
  });

  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);

  const response = await fetch(
    'https://api.agtcloud.cn/v1/realtime?model=MODEL_ID',
    {
      method: 'POST',
      body: offer.sdp,
      headers: {
        Authorization: `Bearer ${ephemeralKey}`,
        'Content-Type': 'application/sdp',
      },
    },
  );

  await pc.setRemoteDescription({
    type: 'answer',
    sdp: await response.text(),
  });
}

init();

import express from 'express';

const app = express();

app.get('/session', async (_request, response) => {
  const result = await fetch('https://api.agtcloud.cn/v1/realtime/sessions', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'MODEL_ID',
      voice: 'verse',
    }),
  });

  response.send(await result.json());
});

app.listen(3000);

const dataChannel = pc.createDataChannel('oai-events');

dataChannel.addEventListener('message', (event) => {
  const realtimeEvent = JSON.parse(event.data);
  console.log(realtimeEvent);
});

dataChannel.send(JSON.stringify({
  type: 'response.create',
  response: {
    modalities: ['text'],
    instructions: 'Напишите хайку о коде',
  },
}));

const ws = new WebSocket(
  'wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID',
  [
    'realtime',
    'openai-insecure-api-key.your-api-key',
    'openai-organization.ORGANIZATION_ID',
    'openai-project.PROJECT_ID',
    'openai-beta.realtime-v1',
  ],
);

ws.addEventListener('open', () => {
  console.log('Соединение с сервером установлено.');
});

ws.addEventListener('message', (event) => {
  console.log(JSON.parse(event.data));
});

Сеансы, аудио и диалоги

Realtime поддерживает текстовые, голосовые и смешанные текстово-аудиодиалоги. Конфигурация сеанса может включать форматы входного и выходного аудио, голос, температуру, максимальную длину вывода, инструменты и параметры VAD.

• Форматы входного и выходного аудио:pcm16, g711_ulaw, g711_alaw.
• Примеры вариантов голоса:alloy, echo, shimmer.
• Конфигурация VAD включает порог, аудиопрефикс перед речью и длительность тишины.
• Диалог развивается через сеанс, элементы диалога, части содержимого и события ответов.

Поля отдельных событий доступны в браузере событий ниже; общие параметры и допустимые значения собраны в разделе «Общие типы».

Справочник событий

Выберите событие, чтобы увидеть определения полей и пример JSON. Можно менять направление событий, фильтровать по категории или искать по названию события.

{
  "event_id": "event_123",
  "type": "session.update",
  "modalities": [
    "text",
    "audio"
  ],
  "instructions": "Отвечайте кратко и точно.",
  "voice": "alloy, echo, shimmer",
  "input_audio_format": "pcm16, g711_ulaw, g711_alaw",
  "output_audio_format": "pcm16, g711_ulaw, g711_alaw",
  "input_audio_transcription": {
    "model": "whisper-1"
  },
  "turn_detection": {
    "type": "server_vad",
    "threshold": 0.8,
    "prefix_padding_ms": 500,
    "silence_duration_ms": 1000
  },
  "tools": [],
  "tool_choice": "auto",
  "temperature": 0.8,
  "max_output_tokens": "inf"
}

Общие типы

В следующих раскрываемых разделах собраны таблицы параметров лимитов частоты, вызовов функций, аудио, VAD, инструментов, моделей, событий, сеансов, элементов диалога, содержимого, ответов, транскрипции, аудиопотоков и WebRTC.

Обработка ошибок и восстановление

Ошибки Realtime обычно связаны с четырьмя категориями проблем: подключением, аутентификацией, аудио или сеансом:

Стратегии восстановления могут включать автоматическое переподключение, восстановление сеанса, ограниченные повторные попытки и переход к упрощённой функциональности. При ошибке сначала прочитайте событие error, сохраните event_id, error.type, error.code, error.message и сведения о связанном событии, а затем решайте, нужна ли повторная отправка.