88API88API
AI-приложенияAPIПомощь и поддержка

Интерфейс разговора в реальном времени OpenAI

📝 Обзор

Введение

OpenAI Realtime API предоставляет два метода подключения:

  1. WebRTC — аудио и видео взаимодействие в реальном времени для браузеров и мобильных клиентов.

  2. WebSocket — для интеграции приложений между серверами.

Сценарии использования

  • Голосовой разговор в реальном времени
  • Аудио и видеоконференции
  • перевод в реальном времени
  • Транскрипция голоса
  • Живая генерация кода
  • Интеграция в реальном времени на стороне сервера

Основные возможности

  • Двусторонняя потоковая передача звука
  • Смешанные текстовые и аудио разговоры
  • Поддержка вызова функций
  • Автоматическое обнаружение голоса (VAD)
  • Функция транскрипции аудио
  • Интеграция на стороне сервера WebSocket

🔐 Аутентификация и безопасность

Метод аутентификации

  1. Стандартный ключ API (используется только на стороне сервера)
  2. Временный токен (используется клиентом)

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

  • Срок действия: 1 минута
  • Ограничение использования: одно соединение
  • Как получить: создано через серверный API.
POST https://88api.ai/v1/realtime/sessions
Content-Type: application/json
Authorization: Bearer $NEW_API_KEY

{
  "model": "gpt-4o-realtime-preview-2024-12-17",
  "voice": "verse"
}

Советы по безопасности

  • Никогда не раскрывайте стандартные ключи API на стороне клиента.
  • Общайтесь по протоколу HTTPS/WSS.
  • Внедрить соответствующие средства контроля доступа.
  • Мониторинг необычной активности

🔌 Соединение установлено

WebRTC-соединение

  • URL-адрес: https://88api.ai/v1/realtime.
  • Параметр запроса: https://88api.ai/v1/realtime
  • Заголовок запроса: -https://88api.ai/v1/realtime -https://88api.ai/v1/realtime

Соединение через веб-сокет

  • URL-адрес: https://88api.ai/v1/realtime.
  • Параметр запроса: https://88api.ai/v1/realtime
  • Заголовок запроса: -https://88api.ai/v1/realtime -https://88api.ai/v1/realtime

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

sequenceDiagram
    participant Client
    participant Server
    participant OpenAI

    alt WebRTC соединять
        Client->>Server: Запросить временный токен
        Server->>OpenAI: Создать сеанс
        OpenAI-->>Server: Вернуть временный токен
        Server-->>Client: Вернуть временный токен

        Client->>OpenAI: создавать WebRTC offer
        OpenAI-->>Client: возвращаться answer

        Note over Client,OpenAI: Учреждать WebRTC соединять

        Client->>OpenAI: Создать канал данных
        OpenAI-->>Client: Подтвердить канал передачи данных
    else WebSocket соединять
        Server->>OpenAI: Учреждать WebSocket соединять
        OpenAI-->>Server: Подтвердите соединение

        Note over Server,OpenAI: Начать живой разговор
    end

Канал данных

  • Имя: oai-events
  • Цель: передача событий
  • Формат: JSON

Потоковое аудио

  • Ввод: oai-events
  • Выход: событие oai-events.

💬 Диалоговое взаимодействие

Режим разговора

  1. Обычный текстовый разговор
  2. Голосовой разговор
  3. Смешанные разговоры

Управление сеансами

  • Создать сеанс
  • Обновление сеанса
  • Завершить сеанс
  • Конфигурация сеанса

Тип события

  • текстовые события
  • аудио события
  • вызов функции
  • Обновления статуса
  • события ошибок

⚙️ Параметры конфигурации

Конфигурация звука

  • Формат ввода -oai-events -oai-events -oai-events
  • Формат вывода -oai-events -oai-events -oai-events
  • Тип голоса -oai-events -oai-events -oai-events

Конфигурация модели

  • температура
  • Максимальная длина вывода
  • Слова системных подсказок
  • Конфигурация инструмента

Конфигурация VAD

  • Порог
  • Продолжительность молчания
  • заполнение префикса

💡 Пример запроса

Соединение WebRTC ❌

Реализация клиента (браузер)

async function init() {
  // Получить временный ключ с сервера - См. код сервера ниже.
  const tokenResponse = await fetch('/session');
  const data = await tokenResponse.json();
  const EPHEMERAL_KEY = data.client_secret.value;

  // Создать одноранговое соединение
  const pc = new RTCPeerConnection();

  // Устанавливает удаленный звук, возвращаемый моделью воспроизведения.
  const audioEl = document.createElement('audio');
  audioEl.autoplay = true;
  pc.ontrack = (e) => (audioEl.srcObject = e.streams[0]);

  // Добавить локальную звуковую дорожку для входа в микрофон браузера
  const ms = await navigator.mediaDevices.getUserMedia({
    audio: true,
  });
  pc.addTrack(ms.getTracks()[0]);

  // Настройте каналы данных для отправки и получения событий
  const dc = pc.createDataChannel('oai-events');
  dc.addEventListener('message', (e) => {
    // Получайте события сервера в реальном времени здесь!
    console.log(e);
  });

  // Использовать протокол описания сеанса(SDP)Начать сеанс
  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);

  const baseUrl = 'https://88api.ai/v1/realtime';
  const model = 'gpt-4o-realtime-preview-2024-12-17';
  const sdpResponse = await fetch(`${baseUrl}?model=${model}`, {
    method: 'POST',
    body: offer.sdp,
    headers: {
      Authorization: `Bearer ${EPHEMERAL_KEY}`,
      'Content-Type': 'application/sdp',
    },
  });

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

init();

Реализация на стороне сервера (Node.js)

import express from 'express';

const app = express();

// Создайте конечную точку для генерации временных токенов.
// Эта конечная точка используется вместе с приведенным выше клиентским кодом.
app.get('/session', async (req, res) => {
  const r = await fetch('https://88api.ai/v1/realtime/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.NEW_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'gpt-4o-realtime-preview-2024-12-17',
      voice: 'verse',
    }),
  });
  const data = await r.json();

  // будет изOpenAI REST APIполученныйJSONОтправить обратно клиенту
  res.send(data);
});

app.listen(3000);

Пример отправки и получения событий WebRTC

// Создайте канал данных из однорангового соединения
const dc = pc.createDataChannel('oai-events');

// Слушайте события сервера на канале данных
// Данные о событии необходимо получить изJSONРазбор строк
dc.addEventListener('message', (e) => {
  const realtimeEvent = JSON.parse(e.data);
  console.log(realtimeEvent);
});

// Отправлять клиентские события:Сериализуйте действительные клиентские события для
// JSON,и отправляется по каналу данных
const responseCreate = {
  type: 'response.create',
  response: {
    modalities: ['text'],
    instructions: 'Write a haiku about code',
  },
};
dc.send(JSON.stringify(responseCreate));

Соединение через WebSocket ✅

Node.js (модуль ws)

import WebSocket from 'ws';

const url =
  'wss://88api.ai/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17';
const ws = new WebSocket(url, {
  headers: {
    Authorization: 'Bearer ' + process.env.NEW_API_KEY,
    'OpenAI-Beta': 'realtime=v1',
  },
});

ws.on('open', function open() {
  console.log('Connected to server.');
});

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

Python (вебсокет-клиент)

# Необходимо установить библиотеку websocket-client:
# pip install websocket-client

import os
import json
import websocket

NEW_API_KEY = os.environ.get("NEW_API_KEY")

url = "wss://88api.ai/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17"
headers = [
    "Authorization: Bearer " + NEW_API_KEY,
    "OpenAI-Beta: realtime=v1"
]

def on_open(ws):
    print("Connected to server.")

def on_message(ws, message):
    data = json.loads(message)
    print("Received event:", json.dumps(data, indent=2))

ws = websocket.WebSocketApp(
    url,
    header=headers,
    on_open=on_open,
    on_message=on_message,
)

ws.run_forever()

Браузер (стандартный WebSocket)

/*
Уведомление:В клиентской среде, такой как браузер,Мы рекомендуем использоватьWebRTC。
Но вDenoиCloudflare WorkersВ среде браузера, такой как,
Вы также можете использовать стандартныйWebSocketинтерфейс。
*/

const ws = new WebSocket(
  'wss://88api.ai/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17',
  [
    'realtime',
    // Сертификация
    'openai-insecure-api-key.' + NEW_API_KEY,
    // Необязательный
    'openai-organization.' + OPENAI_ORG_ID,
    'openai-project.' + OPENAI_PROJECT_ID,
    // Betaпротокол,необходимый
    'openai-beta.realtime-v1',
  ]
);

ws.on('open', function open() {
  console.log('Connected to server.');
});

ws.on('message', function incoming(message) {
  console.log(message.data);
});

Пример отправки и получения сообщения

Node.js/браузер
// Получать события сервера
ws.on('message', function incoming(message) {
  // Нужно начать сJSONАнализ данных сообщения
  const serverEvent = JSON.parse(message.data);
  console.log(serverEvent);
});

// Отправить событие,Создайте формат событий на стороне клиентаJSONструктура данных
const event = {
  type: 'response.create',
  response: {
    modalities: ['audio', 'text'],
    instructions: 'Give me a haiku about code.',
  },
};
ws.send(JSON.stringify(event));
Питон
# Отправлять клиентские события, сериализовать словарь в JSON
def on_open(ws):
    print("Connected to server.")

    event = {
        "type": "response.create",
        "response": {
            "modalities": ["text"],
            "instructions": "Please assist the user."
        }
    }
    ws.send(json.dumps(event))

# Для получения сообщения требуется анализ полезных данных сообщения из JSON.
def on_message(ws, message):
    data = json.loads(message)
    print("Received event:", json.dumps(data, indent=2))

⚠️ Обработка ошибок

Распространенные ошибки

  1. Ошибка подключения
    • Проблемы с сетью
    • Аутентификация не удалась
    • Ошибка конфигурации
  2. Ошибки звука
    • Разрешения устройства
    • Формат не поддерживается
    • Проблемы с кодеком
  3. Ошибка сеанса
    • Срок действия токена истекает
    • Тайм-аут сеанса
    • Ограничения параллелизма

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

  1. Автоматическое переподключение
  2. Восстановление сессии
  3. Повторите попытку в случае ошибки.
  4. Обработка понижения версии

📝 Ссылка на событие

Общий заголовок запроса

Все события должны включать следующие заголовки запросов:

Заголовки запросовТипОписаниеПримеры значений
АвторизацияСтрокаТокен аутентификацииНоситель $NEW_API_KEY
OpenAI-бетаСтрокаверсия APIв реальном времени=v1

Клиентские события

сеанс.обновление

Обновите конфигурацию сеанса по умолчанию.

ПараметрыТипТребуетсяОписаниеПример/необязательные значения
идентификатор_событиястроканетидентификатор события, сгенерированный клиентомсобытие_123
типстроканеттип событиясеанс.обновление
модальностиСтроковый массивНетТипы модальностей, на которые может реагировать модель["текст", "аудио"]
инструкцииСтрокаНетСистемные инструкции, заданные перед вызовом модели«Ваш предел знаний — 2023–2010 годы…»
голосстроканеттип голоса моделисплав, эхо, мерцание
входной_аудио_форматСтрокаНетВходной аудиоформатpcm16, g711_ulaw, g711_alaw
выходной_аудио_форматстрокаНетВыходной аудиоформатpcm16, g711_ulaw, g711_alaw
input_audio_transcription.modelстроканетмодель для транскрипциишепот-1
Turn_detection.typeстроканеттип обнаружения речисервер_вад
Turn_detection.thresholdномернетПорог активации VAD (0,0-1,0)0,8
Turn_detection.prefix_padding_msЦелое числоНетПродолжительность звука, включенная до начала речи500
Turn_detection.silence_duration_msцелое числонетПродолжительность тишины для определения остановки речи1000
инструментымассивнетсписок инструментов, доступных для модели[]
инструмент_выборСтрокаНетКак модель выбирает инструментавто/нет/обязательно
температураномернетмодель температуры отбора проб0,8
max_output_tokensСтрока/целое числоНетМаксимальное количество токенов в одном ответе"инф"/4096

input_audio_buffer.append

Добавьте аудиоданные во входной аудиобуфер.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событиястроканетидентификатор события, сгенерированный клиентомсобытие_456
типстроканеттип событияinput_audio_buffer.append
аудиоСтрокаНетАудиоданные в кодировке Base64Base64EncodedAudioData

input_audio_buffer.commit

Отправьте аудиоданные в буфер как сообщение пользователя.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событиястроканетидентификатор события, сгенерированный клиентомсобытие_789
типстроканеттип событияinput_audio_buffer.commit

input_audio_buffer.clear

Очищает все аудиоданные во входном аудиобуфере.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событиястроканетидентификатор события, сгенерированный клиентомсобытие_012
типстроканеттип событияinput_audio_buffer.clear

разговор.item.create

Добавляйте в беседу новые элементы беседы.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событиястроканетидентификатор события, сгенерированный клиентомсобытие_345
типстроканеттип событияразговор.item.create
предыдущий_item_idСтрокаНетНовые элементы разговора будут вставлены после этого идентификатораноль
элемент.idСтрокаНетУникальный идентификатор элемента беседысообщение_001
тип элементаСтрокаНетТип элемента диалогового окнасообщение/вызов_функции/вызов_функции
элемент.статусСтрокаНетСтатус элемента диалогазавершено/in_progress/незавершено
элемент.рольСтрокаНетРоль отправителя сообщенияпользователь/помощник/система
элемент.содержаниеМассивНетСодержание сообщения[текст/аудио/расшифровка]
item.call_idСтрокаНетID вызова функциивызов_001
имя_предметаСтрокаНетИмя вызываемой функцииимя_функции
элемент.аргументыСтрокаНетПараметры для вызова функции{"парам": "значение"}
элемент.выводСтрокаНетВыходной результат вызова функции{"результат": "значение"}

разговор.item.truncate

Усекать аудиоконтент в сообщениях Ассистента.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событиястроканетидентификатор события, сгенерированный клиентомсобытие_678
типстроканеттип событияразговор.элемент.truncate
идентификатор_предметастроканетИдентификатор элемента сообщения помощника, который нужно усечьсообщение_002
индекс_содержимогоцелое числонетиндекс части содержимого для усечения0
audio_end_msцелое числонетмомент окончания обрезания звука1500

разговор.элемент.удалить

Удаляет указанный элемент беседы из истории бесед.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событиястроканетидентификатор события, сгенерированный клиентомсобытие_901
типстроканеттип событияразговор.элемент.удалить
идентификатор_предметаСтрокаНетID элемента беседы, который нужно удалитьсообщение_003

ответ.создать

Генерация триггерного ответа.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событиястроканетидентификатор события, сгенерированный клиентомсобытие_234
типстроканеттип событияответ.создать
ответ.модальностиСтроковый массивНетМодальный тип ответа["текст", "аудио"]
ответ.инструкцииСтрокаНетИнструкция к модели«Пожалуйста, помогите пользователю».
ответ.голосСтрокаНетТип голоса моделисплав/эхо/мерцание
ответ.output_audio_formatстроканетвыходной аудиоформатПКМ16
ответ.инструментыМассивНетСписок инструментов, доступных для модели["тип", "имя", "описание"]
ответ.tool_choiceстроканетМетод инструмента выбора моделиавто
ответ.температураномернеттемпература образца0,7
response.max_output_tokensЦелое число/строкаНетМаксимальное количество выходных токенов150/"инф"

ответ.отмена

Отменяет генерацию ответа в процессе.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событиястроканетидентификатор события, сгенерированный клиентомсобытие_567
типстроканеттип событияответ.отмена

События на стороне сервера

ошибка

Событие возвращается при возникновении ошибки.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтроковый массивНетУникальный идентификатор события сервера["событие_890"]
типстроканеттип событияошибка
ошибка.типстроканеттип ошибкинедопустимая_ошибка_запроса/ошибка_сервера
ошибка.кодстроканеткод ошибкинедопустимое_событие
ошибка.сообщениеСтрокаНетЧитабельное сообщение об ошибке«Поле «тип» отсутствует».
ошибка.парамстроканетпараметры, связанные с ошибкаминоль
error.event_idСтрокаНетID связанного событиясобытие_567

разговор.item.input_audio_transcription.completed

Это событие возвращается, когда включена функция транскрипции входного аудио и транскрипция прошла успешно.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_2122
типстроканеттип событияразговор.item.input_audio_transcription.completed
идентификатор_предметаСтрокаНетID элемента сообщения пользователясообщение_003
индекс_содержимогоЦелое числоНетИндекс части контента, содержащей аудио0
стенограммастроканетрасшифрованный текстовый контент"Привет, как дела?"

разговор.item.input_audio_transcription.failed

Это событие возвращается, когда настроена функция транслитерации входного аудио, но запрос транслитерации для пользовательских сообщений завершается неудачей.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_2324
типстроковый массивнеттип события["conversation.item.input_audio_transcription.failed"]
идентификатор_предметаСтрокаНетID элемента сообщения пользователясообщение_003
индекс_содержимогоЦелое числоНетИндекс части контента, содержащей аудио0
ошибка.типстроканеттип ошибкитранскрипция_ошибка
ошибка.кодстроканеткод ошибкиaudio_unintelligible
ошибка.сообщениеСтрокаНетЧитабельное сообщение об ошибке«Аудио не удалось расшифровать».
ошибка.парамстроканетпараметры, связанные с ошибкаминоль

разговор.элемент.усеченный

Это событие возвращается, когда клиент обрезал предыдущий элемент аудиосообщения помощника.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_2526
типстроканеттип событияразговор.элемент.усеченный
идентификатор_предметаСтрокаНетИдентификатор усеченного элемента сообщения помощникасообщение_004
индекс_содержимогоцелое числонетиндекс усеченной части контента0
audio_end_msЦелое числоНетМомент времени, в котором звук обрезается (миллисекунды)1500

разговор.элемент.удален

Это событие возвращается, когда элемент в беседе удаляется.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_2728
типстроканеттип событияразговор.элемент.удален
идентификатор_предметаСтрокаНетИдентификатор удаленного элемента беседысообщение_005

input_audio_buffer.commited

Это событие возвращается, когда данные в аудиобуфере фиксируются.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_1121
типстроканеттип событияinput_audio_buffer.commited
предыдущий_item_idСтрокаНетНовый элемент разговора будет вставлен после элемента разговора, соответствующего этому идентификаторусообщение_001
идентификатор_предметаСтрокаНетИдентификатор создаваемого элемента сообщения пользователясообщение_002

input_audio_buffer.cleared

Это событие возвращается, когда клиент очищает входной аудиобуфер.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_1314
типстроканеттип событияinput_audio_buffer.cleared

input_audio_buffer.speech_started

В режиме обнаружения речи сервера это событие возвращается при обнаружении речевого ввода.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_1516
типстроканеттип событияinput_audio_buffer.speech_started
audio_start_msЦелое числоНетКоличество миллисекунд от начала сеанса до обнаружения речи1000
идентификатор_предметастроканетID элемента сообщения пользователя, который будет создан при остановке речисообщение_003

input_audio_buffer.speech_stopped

В режиме обнаружения речи сервера это событие возвращается при обнаружении прекращения речевого ввода.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_1718
типстроканеттип событияinput_audio_buffer.speech_stopped
audio_start_msцелое числонетКоличество миллисекунд от начала сеанса до обнаружения прекращения речи2000
идентификатор_предметаСтрокаНетИдентификатор создаваемого элемента сообщения пользователясообщение_003

ответ.создан

Это событие возвращается при создании нового ответа.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_2930
типстроканеттип событияответ.создано
ответ.idСтрокаНетУникальный идентификатор ответаresp_001
ответ.объектстроканеттип объектареалтайм.ответ
ответ.статусстроканетстатус ответав_прогрессе
ответ.статус_деталиОбъектНетДополнительная информация о статусеноль
ответ.выходСтроковый массивНетСписок элементов вывода, сгенерированных ответом["[]"]
ответ.использованиеОбъектНетСтатистика использования ответаноль

ответ.готово

Это событие возвращается после завершения потоковой передачи ответа.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_3132
типстроканеттип событияответ.сделано
ответ.idСтрокаНетУникальный идентификатор ответаresp_001
ответ.объектстроканеттип объектареалтайм.ответ
ответ.статусСтрокаНетОкончательный статус ответазавершено/отменено/не выполнено/не завершено
ответ.статус_деталиОбъектНетДополнительная информация о статусеноль
ответ.выходСтроковый массивНетСписок элементов вывода, сгенерированных ответом["[...]"]
ответ.usage.total_tokensЦелое числоНетОбщее количество токенов50
ответ.usage.input_tokensЦелое числоНетКоличество входных токенов20
ответ.использование.выходные_токеныЦелое числоНетКоличество выходных жетонов30

response.output_item.added

Это событие возвращается, когда во время генерации ответа создается новый элемент вывода.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_3334
типстроканеттип событияответ.выходной_элемент.добавлен
идентификатор_ответаСтрокаНетИдентификатор ответа, которому принадлежит выходной элементresp_001
выходной_индексСтрокаНетИндекс выходного элемента в ответе0
элемент.idСтрокаНетУникальный идентификатор выходного элементасообщение_007
элемент.объектстроканеттип объектав реальном времени.предмет
тип элементастроканеттип выходного элементасообщение/вызов_функции/вызов_функции
элемент.статусСтрокаНетСтатус выходного элементаin_progress/завершено
элемент.рольСтрокаНетРоль, связанная с выходным элементомпомощник
элемент.содержаниеМассивНетВывод содержимого элемента["тип", "текст", "аудио", "расшифровка"]

ответ.output_item.done

Это событие возвращается, когда элемент вывода завершает потоковую передачу.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор событий на стороне серверасобытие_3536
типстроканеттип событияответ.выходной_элемент.сделано
идентификатор_ответаСтрокаНетИдентификатор ответа, которому принадлежит выходной элементresp_001
выходной_индексСтрокаНетИндекс выходного элемента в ответе0
элемент.idСтрокаНетУникальный идентификатор выходного элементасообщение_007
элемент.объектстроканеттип объектав реальном времени.предмет
тип элементастроканеттип выходного элементасообщение/вызов_функции/вызов_функции
элемент.статусСтрокаНетОкончательный статус выходного элементазавершено/незавершено
элемент.рольСтрокаНетРоль, связанная с выходным элементомпомощник
элемент.содержаниеМассивНетВывод содержимого элемента["тип", "текст", "аудио", "расшифровка"]

response.content_part.added

Это событие возвращается, когда новая часть содержимого добавляется к элементу вспомогательного сообщения во время генерации ответа.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_3738
типстроканеттип событияответ.content_part.добавлено
идентификатор_ответастроканетидентификатор ответаresp_001
идентификатор_предметаСтрокаНетДобавьте идентификатор элемента сообщения части содержимогосообщение_007
выходной_индексцелое числоНетИндекс выходного элемента в ответе0
индекс_содержимогоЦелое числоНетИндекс части содержимого в массиве содержимого элемента сообщения0
тип деталистроканеттип контентатекст/аудио
часть.текстСтрокаНетТекстовый контент«Привет»
часть.аудиоСтрокаНетАудиоданные в кодировке Base64"base64_encoded_audio_data"
часть.транскриптСтрокаНетРасшифровка текста аудиозаписи«Привет»

ответ.content_part.done

Это событие возвращается, когда содержимое элемента вспомогательного сообщения частично завершило потоковую передачу.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_3940
типстроканеттип событияответ.content_part.done
идентификатор_ответастроканетидентификатор ответаresp_001
идентификатор_предметаСтрокаНетДобавьте идентификатор элемента сообщения части содержимогосообщение_007
выходной_индексцелое числоНетИндекс выходного элемента в ответе0
индекс_содержимогоЦелое числоНетИндекс части содержимого в массиве содержимого элемента сообщения0
тип деталистроканеттип контентатекст/аудио
часть.текстСтрокаНетТекстовый контент«Привет»
часть.аудиоСтрокаНетАудиоданные в кодировке Base64"base64_encoded_audio_data"
часть.транскриптСтрокаНетРасшифровка текста аудиозаписи«Привет»

ответ.текст.дельта

Это событие возвращается при обновлении текстового значения части содержимого типа «текст».

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_4142
типстроканеттип событияответ.текст.дельта
идентификатор_ответастроканетидентификатор ответаresp_001
идентификатор_предметаСтрокаНетID элемента сообщениясообщение_007
выходной_индексцелое числоНетИндекс выходного элемента в ответе0
индекс_содержимогоЦелое числоНетИндекс части содержимого в массиве содержимого элемента сообщения0
дельтастроканеттекстовое добавочное обновление содержимого«Конечно, могу»

ответ.текст.сделано

Это событие возвращается, когда потоковая передача текста для части контента типа «текст» завершена.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_4344
типстроканеттип событияответ.текст.сделано
идентификатор_ответастроканетидентификатор ответаresp_001
идентификатор_предметаСтрокаНетID элемента сообщениясообщение_007
выходной_индексцелое числоНетИндекс выходного элемента в ответе0
индекс_содержимогоЦелое числоНетИндекс части содержимого в массиве содержимого элемента сообщения0
дельтастроканетокончательный полнотекстовый контент«Конечно, я могу с этим помочь».

response.audio_transcript.delta

Это событие возвращается при обновлении транскрипции вывода звука, созданной моделью.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_4546
типстроканеттип событияответ.audio_transcript.delta
идентификатор_ответастроканетидентификатор ответаresp_001
идентификатор_предметаСтрокаНетID элемента сообщениясообщение_008
выходной_индексцелое числоНетИндекс выходного элемента в ответе0
индекс_содержимогоЦелое числоНетИндекс части содержимого в массиве содержимого элемента сообщения0
дельтастроканетпостепенное обновление транскрибируемого текста«Привет, как я могу»

response.audio_transcript.done

Это событие возвращается, когда транскрипция вывода звука, созданная моделью, завершает потоковую передачу.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_4748
типстроканеттип событияответ.audio_transcript.done
идентификатор_ответастроканетидентификатор ответаresp_001
идентификатор_предметаСтрокаНетID элемента сообщениясообщение_008
выходной_индексцелое числоНетИндекс выходного элемента в ответе0
индекс_содержимогоЦелое числоНетИндекс части содержимого в массиве содержимого элемента сообщения0
стенограммаСтрокаНетОкончательная полная расшифровка аудио«Здравствуйте, чем я могу вам помочь сегодня?»

ответ.аудио.дельта

Это событие возвращается при обновлении аудиоконтента, созданного моделью.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_4950
типстроканеттип событияответ.аудио.дельта
идентификатор_ответастроканетидентификатор ответаresp_001
идентификатор_предметаСтрокаНетID элемента сообщениясообщение_008
выходной_индексцелое числоНетИндекс выходного элемента в ответе0
индекс_содержимогоЦелое числоНетИндекс части содержимого в массиве содержимого элемента сообщения0
дельтаСтрокаНетДельта аудиоданных в кодировке Base64«Base64EncodedAudioDelta»

ответ.аудио.сделано

Это событие возвращается, когда генерация звука моделью завершена.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_5152
типстроканеттип событияответ.аудио.сделано
идентификатор_ответастроканетидентификатор ответаresp_001
идентификатор_предметаСтрокаНетID элемента сообщениясообщение_008
выходной_индексцелое числоНетИндекс выходного элемента в ответе0
индекс_содержимогоЦелое числоНетИндекс части содержимого в массиве содержимого элемента сообщения0

Вызов функции

response.function_call_arguments.delta

Это событие возвращается при обновлении параметров вызова функции, созданных моделью.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_5354
типстроканеттип событияответ.функция_call_arguments.delta
идентификатор_ответастроканетидентификатор ответаresp_002
идентификатор_предметаСтрокаНетID элемента сообщенияФК_001
выходной_индексцелое числоНетИндекс выходного элемента в ответе0
идентификатор_вызоваСтрокаНетID вызова функциивызов_001
дельтаСтрокаНетПриращение параметра вызова функции в формате JSON{"местоположение": "Сан"}

response.function_call_arguments.done

Это событие возвращается, когда параметры вызова функции, созданные моделью, завершили потоковую передачу.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_5556
типстроканеттип событияответ.функция_call_arguments.done
идентификатор_ответастроканетидентификатор ответаresp_002
идентификатор_предметаСтрокаНетID элемента сообщенияФК_001
выходной_индексцелое числоНетИндекс выходного элемента в ответе0
идентификатор_вызоваСтрокаНетID вызова функциивызов_001
аргументыСтрокаНетОкончательные параметры полного вызова функции (формат JSON){"местоположение": "Сан-Франциско"}

Другие обновления статуса

####rate_limits.обновлено

Срабатывает после каждого события «response.done», чтобы указать обновленное ограничение скорости.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_5758
типстроканеттип событияrate_limits.обновлено
предел_рейтаМассив объектовНетСписок информации об ограничении скорости[{"name": "requests_per_min", "limit": 60, "remaining": 45, "reset_seconds": 35}]

разговор.создан

Это событие возвращается при создании разговора.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_9101
типстроканеттип событияразговор.создан
разговоробъектнетобъект ресурса разговора[{"name": "requests_per_min", "limit": 60, "remaining": 45, "reset_seconds": 35}]

разговор.элемент.создан

Это событие возвращается при создании элемента диалога.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_1920
типстроканеттип событияразговор.элемент.создан
предыдущий_item_idСтрокаНетID предыдущего элемента беседысообщение_002
предметобъектнетобъект элемента диалога{"id": "msg_003", "object": "realtime.item", "type": "message", "status": "completed", "role": "user", "content": [{"type": "text", "text": "Hello"}]}

сеанс.создан

Это событие возвращается при создании сеанса.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_1234
типстроканеттип событиясеанс.создан
сессияобъектнетобъект сеанса{"id": "sess_001", "object": "realtime.session", "model": "gpt-4", "modalities": ["text", "audio"]}

сеанс.обновлено

Это событие возвращается при обновлении сеанса.

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событияСтрокаНетУникальный идентификатор события на стороне серверасобытие_5678
типстроканеттип событиясеанс.обновлено
сессияобъектнетобновленный объект сеанса{"id": "sess_001", "object": "realtime.session", "model": "gpt-4", "modalities": ["text", "audio"]}

Таблица параметров событий ограничения скорости

ПараметрыТипТребуетсяОписаниеПримеры значений
имястрокадаимя лимитазапросов_пер_мин
пределцелое числодапредельное значение60
осталосьцелое числодаосталось в наличии45
сброс_секундцелое числодавремя сброса (секунды)35

Список параметров вызова функции

ПараметрыТипТребуетсяОписаниеПримеры значений
типстрокадатип функциифункция
имястрокадаимя функцииполучить_погоду
описаниеСтрокаНетОписание функцииПолучить текущую погоду
параметрыобъектдаопределение параметра функции{"id": "sess_001", "object": "realtime.session", "model": "gpt-4", "modalities": ["text", "audio"]}

Таблица параметров аудиоформата

ПараметрыТипОписаниеНеобязательные значения
частота_выборкицелое числочастота дискретизации8000, 16000, 24000, 44100, 48000
каналыцелое числоколичество каналов1 (моно), 2 (стерео)
бит_на_выборкуцелое числоколичество бит выборки16 (пкм16), 8 (г711)
кодированиестрокаметод кодированияpcm16, g711_ulaw, g711_alaw

Таблица параметров обнаружения голоса

ПараметрыТипОписаниеЗначение по умолчаниюДиапазон
порогчисло с плавающей запятойПорог активации VAD0,50,0-1,0
prefix_padding_msцелое числозаполнение речевого префикса (миллисекунды)5000-5000
молчание_длительность_мсЦелое числоПродолжительность обнаружения тишины (миллисекунды)1000100-10000

Таблица параметров выбора инструмента

ПараметрыТипОписаниеНеобязательные значения
инструмент_выборстрокаметод выбора инструментаавто, нет, требуется
инструментымассивсписок доступных инструментов[{type, name, description, parameters}]

Таблица параметров конфигурации модели

ПараметрыТипОписаниеДиапазон/необязательные значенияЗначение по умолчанию
температурачисло с плавающей запятойтемпература отбора проб0,0-2,01.0
max_output_tokensцелое число/строкамаксимальная длина вывода1-4096/"инф""инф"
модальностистроковый массивспособы реагирования["текст", "аудио"]["текст"]
голосстрокатип голосасплав, эхо, мерцаниесплав

Таблица общих параметров событий

ПараметрыТипТребуетсяОписаниеПримеры значений
идентификатор_событиястрокадауникальный идентификатор событиясобытие_123
типстрокадатип событиясеанс.обновление
временная меткацелое числоНетвременная метка, когда произошло событие (миллисекунды)1677649363000

Таблица параметров состояния сеанса

ПараметрыТипОписаниеНеобязательные значения
статусстрокастатус сеансаактивен, завершен, ошибка
ошибкаобъектсообщение об ошибке{"type": "error_type", "message": "error message"}
метаданныеобъектметаданные сеанса{"type": "error_type", "message": "error message"}

Таблица параметров статуса элемента диалога

ПараметрыТипОписаниеНеобязательные значения
статусстрокастатус элемента диалогазавершено, в_прогрессе, неполное
рольстрокароль отправителяпользователь, помощник, система
типстрокатип элемента диалогового окнасообщение, вызов_функции, вывод_вызова функции

Таблица параметров типа контента

ПараметрыТипОписаниеНеобязательные значения
типстрокатип контентатекст, аудио, расшифровка
форматстрокаформат контентапростой, уценка, HTML
кодированиестрокаметод кодированияutf-8, base64

Таблица параметров статуса ответа

ПараметрыТипОписаниеНеобязательные значения
статусстрокастатус ответазавершено, отменено, не выполнено, неполное
статус_деталиОбъектДетали статуса{"reason": "user_cancelled"}
использованиеобъектстатистика использования{"reason": "user_cancelled"}

Таблица параметров транскрипции аудио

ПараметрыТипОписаниеПримеры значений
включенЛогическое значениеВключить ли транслитерациюправда
модельстрокамодель транслитерациишепот-1
языкстрокаязык транслитерацииен, ж, авто
подсказатьстрокаРасшифровка подсказки слова«Стенограмма разговора»

Таблица параметров аудиопотока

ПараметрыТипОписаниеНеобязательные значения
размер_кускацелое числоРазмер аудиоблока (в байтах)1024, 2048, 4096
задержкастрокарежим задержкинизкий, сбалансированный, высокий
сжатиестрокаметод сжатиянет, опус, mp3

Таблица параметров конфигурации WebRTC

ПараметрыТипОписаниеЗначение по умолчанию
лед_серверымассивСписок серверов ICE[{"urls": "stun:stun.l.google.com:19302"}]
аудио_ограниченияОбъектАудио ограничения[{"urls": "stun:stun.l.google.com:19302"}]
тайм-аут соединенияцелое числотаймаут соединения (миллисекунды)30000

Содержание

📝 Обзор
Введение
Сценарии использования
Основные возможности
🔐 Аутентификация и безопасность
Метод аутентификации
Временный токен
Советы по безопасности
🔌 Соединение установлено
WebRTC-соединение
Соединение через веб-сокет
Процесс подключения
Канал данных
Потоковое аудио
💬 Диалоговое взаимодействие
Режим разговора
Управление сеансами
Тип события
⚙️ Параметры конфигурации
Конфигурация звука
Конфигурация модели
Конфигурация VAD
💡 Пример запроса
Соединение WebRTC ❌
Реализация клиента (браузер)
Реализация на стороне сервера (Node.js)
Пример отправки и получения событий WebRTC
Соединение через WebSocket ✅
Node.js (модуль ws)
Python (вебсокет-клиент)
Браузер (стандартный WebSocket)
Пример отправки и получения сообщения
Node.js/браузер
Питон
⚠️ Обработка ошибок
Распространенные ошибки
Восстановление ошибок
📝 Ссылка на событие
Общий заголовок запроса
Клиентские события
сеанс.обновление
input_audio_buffer.append
input_audio_buffer.commit
input_audio_buffer.clear
разговор.item.create
разговор.item.truncate
разговор.элемент.удалить
ответ.создать
ответ.отмена
События на стороне сервера
ошибка
разговор.item.input_audio_transcription.completed
разговор.item.input_audio_transcription.failed
разговор.элемент.усеченный
разговор.элемент.удален
input_audio_buffer.commited
input_audio_buffer.cleared
input_audio_buffer.speech_started
input_audio_buffer.speech_stopped
ответ.создан
ответ.готово
response.output_item.added
ответ.output_item.done
response.content_part.added
ответ.content_part.done
ответ.текст.дельта
ответ.текст.сделано
response.audio_transcript.delta
response.audio_transcript.done
ответ.аудио.дельта
ответ.аудио.сделано
Вызов функции
response.function_call_arguments.delta
response.function_call_arguments.done
Другие обновления статуса
разговор.создан
разговор.элемент.создан
сеанс.создан
сеанс.обновлено
Таблица параметров событий ограничения скорости
Список параметров вызова функции
Таблица параметров аудиоформата
Таблица параметров обнаружения голоса
Таблица параметров выбора инструмента
Таблица параметров конфигурации модели
Таблица общих параметров событий
Таблица параметров состояния сеанса
Таблица параметров статуса элемента диалога
Таблица параметров типа контента
Таблица параметров статуса ответа
Таблица параметров транскрипции аудио
Таблица параметров аудиопотока
Таблица параметров конфигурации WebRTC