Справочник по API трансляции голосовой связи

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

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

Ключевые функции

• Обработка звука в режиме реального времени: поддержка нескольких звуковых форматов, включая PCM16 с различными тарифами выборки и кодеками G.711
• Дополнительные параметры голосовой связи: голос OpenAI, пользовательские голоса Azure, стандартные голоса Azure и личные голоса Azure
• Интеграция аватара: потоковая передача аватаров на основе WebRTC с видео, анимацией и смешиваниями
• Интеллектуальное обнаружение поворотов: несколько вариантов VAD, включая семантику VAD Azure и обнаружение на стороне сервера
• Улучшение звука: встроенное снижение шума и отмена эхо
• Вызов функций: интеграция инструментов для расширенных возможностей беседы
• Гибкое управление сеансами: настраиваемые модальности, инструкции и параметры ответа

События клиента

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

session.update

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

Структура событий

{
  "type": "session.update",
  "session": {
    "modalities": ["text", "audio"],
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "instructions": "You are a helpful assistant. Be concise and friendly.",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Свойства

Пример с пользовательским голосом Azure

{
  "type": "session.update",
  "session": {
    "voice": {
      "type": "azure-custom",
      "name": "my-custom-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "temperature": 0.7,
      "style": "cheerful"
    },
    "input_audio_noise_reduction": {
      "type": "azure_deep_noise_suppression"
    },
    "avatar": {
      "character": "lisa",
      "customized": false,
      "video": {
        "resolution": {
          "width": 1920,
          "height": 1080
        },
        "bitrate": 2000000
      }
    }
  }
}

session.аватар.connect

Установите подключение аватара, предоставив клиенту предложение SDP (протокол описания сеанса) для согласования мультимедиа WebRTC. Это событие необходимо при использовании функций аватара.

Структура событий

{
  "type": "session.avatar.connect",
  "client_sdp": "<client_sdp>"
}

Свойства

input_audio_buffer.append

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

Структура событий

{
  "type": "input_audio_buffer.append",
  "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

Свойства

input_audio_buffer.commit

Зафиксируйте входной звуковой буфер для обработки.

Структура событий

{
  "type": "input_audio_buffer.commit"
}

Свойства

input_audio_buffer.clear

Снимите входной звуковой буфер.

Структура событий

{
  "type": "input_audio_buffer.clear"
}

Свойства

conversation.item.create

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

Структура событий

{
  "type": "conversation.item.create",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

Свойства

Пример с аудиоконтентом

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello there"
      }
    ]
  }
}

Пример вызова функции

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call",
    "name": "get_weather",
    "call_id": "call_123",
    "arguments": "{\"location\": \"San Francisco\", \"unit\": \"celsius\"}"
  }
}

Пример вызова MCP

{
  "type": "conversation.item.create",
  "item": {
    "type": "mcp_call",
    "approval_request_id": null,
    "arguments": "",
    "server_label": "deepwiki",
    "name": "ask_question",
    "output": null,
    "error": null
  }
}

conversation.item.retrieve

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

Структура событий

{
  "type": "conversation.item.retrieve",
  "item_id": "item_ABC123"
}

Свойства

conversation.item.truncate

Усечение звукового содержимого сообщения помощника. Это полезно для остановки воспроизведения в определенной точке и синхронизации понимания сервера с состоянием клиента.

Структура событий

{
  "type": "conversation.item.truncate",
  "item_id": "item_ABC123",
  "content_index": 0,
  "audio_end_ms": 5000
}

Свойства

conversation.item.delete

Удалите элемент из журнала бесед.

Структура событий

{
  "type": "conversation.item.delete",
  "item_id": "item_ABC123"
}

Свойства

response.create

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

Структура событий

{
  "type": "response.create",
  "response": {
    "modalities": ["text", "audio"],
    "instructions": "Be extra helpful and detailed.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "output_audio_format": "pcm16",
    "temperature": 0.7,
    "max_response_output_tokens": 1000
  }
}

Свойства

Пример с выбором инструмента

{
  "type": "response.create",
  "response": {
    "modalities": ["text"],
    "tools": [
      {
        "type": "function",
        "name": "get_current_time",
        "description": "Get the current time",
        "parameters": {
          "type": "object",
          "properties": {}
        }
      }
    ],
    "tool_choice": "get_current_time",
    "temperature": 0.3
  }
}

Пример с анимацией

{
  "type": "response.create",
  "response": {
    "modalities": ["audio", "animation"],
    "animation": {
      "model_name": "default",
      "outputs": ["blendshapes", "viseme_id"]
    },
    "voice": {
      "type": "azure-custom",
      "name": "my-expressive-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "style": "excited"
    }
  }
}

response.cancel

Отмена ответа на ход выполнения. Это немедленно останавливает создание ответов и связанные звуковые выходные данные.

Структура событий

{
  "type": "response.cancel"
}

Свойства

Свойства

RealtimeClientEventConversationItemTruncate

Событие клиента conversation.item.truncate используется для усечения звука предыдущего помощника. Сервер создает звук быстрее, чем в режиме реального времени, поэтому это событие полезно, когда пользователь прерывает усечение звука, отправленного клиенту, но еще не воспроизводится. Понимание звука сервера с воспроизведением клиента синхронизируется.

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

Если событие клиента успешно выполнено, сервер отвечает на conversation.item.truncated событие.

Структура событий

{
  "type": "conversation.item.truncate",
  "item_id": "<item_id>",
  "content_index": 0,
  "audio_end_ms": 0
}

Свойства

RealtimeClientEventInputAudioBufferAppend

Событие клиента input_audio_buffer.append используется для добавления звуковых байтов в входной звуковой буфер. Буфер звука — это временное хранилище, в который можно записать и позже зафиксировать.

В режиме обнаружения действий голосовой связи сервера буфер звука используется для обнаружения речи, а сервер решает, когда зафиксировать. При отключении VAD сервера клиент может выбрать, сколько звука должно размещаться в каждом событии не более 15 МиБ. Например, потоковая передача небольших блоков от клиента может позволить VAD быть более адаптивным.

В отличие от большинства других событий клиента, сервер не отправляет ответ подтверждения на событие клиента input_audio_buffer.append .

Структура событий

{
  "type": "input_audio_buffer.append",
  "audio": "<audio>"
}

Свойства

RealtimeClientEventInputAudioBufferClear

Событие клиента input_audio_buffer.clear используется для очистки звуковых байтов в буфере.

Сервер отвечает на input_audio_buffer.cleared событие.

Структура событий

{
  "type": "input_audio_buffer.clear"
}

Свойства

RealtimeClientEventInputAudioBufferCommit

Событие клиента input_audio_buffer.commit используется для фиксации входного звукового буфера пользователя, который создает новый элемент сообщения пользователя в беседе. Звук транскрибируется, если input_audio_transcription настроен для сеанса.

Если в режиме VAD сервера клиент не должен отправлять это событие, сервер автоматически фиксирует буфер звука. Без vaD сервера клиент должен зафиксировать звуковой буфер, чтобы создать элемент сообщения пользователя. Это событие клиента приводит к ошибке, если входной звуковой буфер пуст.

Фиксация входного звукового буфера не создает ответ от модели.

Сервер отвечает на input_audio_buffer.committed событие.

Структура событий

{
  "type": "input_audio_buffer.commit"
}

Свойства

RealtimeClientEventResponseCancel

Событие клиента response.cancel используется для отмены ответа на ход выполнения.

Сервер будет отвечать на response.done событие с состоянием response.status=cancelled.

Структура событий

{
  "type": "response.cancel"
}

Свойства

RealtimeClientEventResponseCreate

Событие клиента response.create используется для указания серверу создать ответ с помощью вывода модели. Если сеанс настроен в режиме VAD сервера, сервер автоматически создает ответы.

Ответ включает по крайней мере один item, и может иметь два, в этом случае второй — вызов функции. Эти элементы добавляются в журнал бесед.

Сервер реагирует на response.created событие, одно или несколько событий элемента и содержимого (например conversation.item.created , и response.content_part.added), и, наконец response.done , событие, указывающее, что ответ завершен.

Структура событий

{
  "type": "response.create"
}

Свойства

RealtimeClientEventSessionUpdate

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

Обновляются только те поля, которые присутствуют. Чтобы очистить поле (например instructions, ), передайте пустую строку.

Сервер отвечает на session.updated событие, содержащее полную эффективную конфигурацию.

Структура событий

{
  "type": "session.update"
}

Свойства

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

Api голосовой трансляции отправляет следующие события сервера для обмена данными о состоянии, ответах и данных клиенту:

session.created

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

Структура событий

{
  "type": "session.created",
  "session": {
    "id": "sess_ABC123DEF456",
    "object": "realtime.session",
    "model": "gpt-realtime",
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful assistant.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Свойства

session.обновлен

Отправляется при успешном обновлении конфигурации сеанса session.update в ответ на событие клиента.

Структура событий

{
  "type": "session.updated",
  "session": {
    "id": "sess_ABC123DEF456",
    "voice": {
      "type": "azure-custom",
      "name": "my-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012"
    },
    "temperature": 0.7,
    "avatar": {
      "character": "lisa",
      "customized": false
    }
  }
}

Свойства

session.avatar.connecting

Указывает, что устанавливается подключение WebRTC аватара. Это событие отправляется в ответ на session.avatar.connect событие клиента.

Структура событий

{
  "type": "session.avatar.connecting",
  "server_sdp": "<server_sdp>"
}

Свойства

conversation.item.created

Отправляется при добавлении нового элемента в беседу через событие клиента conversation.item.create или автоматически во время создания ответа.

Структура событий

{
  "type": "conversation.item.created",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

Свойства

Пример с элементом аудио

{
  "type": "conversation.item.created",
  "item": {
    "id": "item_GHI789",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": null,
        "transcript": "What's the weather like today?"
      }
    ]
  }
}

conversation.item.retrieved

Отправляется в ответ на событие клиента, предоставляя запрошенный conversation.item.retrieve элемент беседы.

Свойства

conversation.item.усечено

Событие сервера conversation.item.truncated возвращается при усечении предыдущего элемента звукового сообщения помощника с событием conversation.item.truncate . Это событие используется для синхронизации понимания сервера звука с воспроизведением клиента.

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

Структура событий

{
  "type": "conversation.item.truncated",
  "item_id": "<item_id>",
  "content_index": 0,
  "audio_end_ms": 0
}

Свойства

conversation.item.deleted

Отправлено в ответ на событие клиента, убедив, что указанный conversation.item.delete элемент был удален из беседы.

Структура событий

{
  "type": "conversation.item.deleted",
  "item_id": "item_ABC123"
}

Свойства

response.created

Отправляется при начале создания нового ответа. Это первое событие в последовательности откликов.

Структура событий

{
  "type": "response.created",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "in_progress",
    "status_details": null,
    "output": [],
    "usage": {
      "total_tokens": 0,
      "input_tokens": 0,
      "output_tokens": 0
    }
  }
}

Свойства

response.done

Отправляется после завершения создания ответов. Это событие содержит окончательный ответ со всеми выходными элементами и статистикой использования.

Структура событий

{
  "type": "response.done",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "completed",
    "status_details": null,
    "output": [
      {
        "id": "item_DEF456",
        "object": "realtime.item",
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
          }
        ]
      }
    ],
    "usage": {
      "total_tokens": 87,
      "input_tokens": 52,
      "output_tokens": 35,
      "input_token_details": {
        "cached_tokens": 0,
        "text_tokens": 45,
        "audio_tokens": 7
      },
      "output_token_details": {
        "text_tokens": 15,
        "audio_tokens": 20
      }
    }
  }
}

Свойства

response.output_item.added

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

Структура событий

{
  "type": "response.output_item.added",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "in_progress",
    "role": "assistant",
    "content": []
  }
}

Свойства

response.output_item.done

Отправляется после завершения выходного элемента.

Структура событий

{
  "type": "response.output_item.done",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello! I'm doing well, thank you for asking."
      }
    ]
  }
}

Свойства

response.content_part.added

Событие сервера response.content_part.added возвращается при добавлении новой части содержимого в элемент сообщения помощника во время создания ответа.

Структура событий

{
  "type": "response.content_part.added",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": ""
  }
}

Свойства

response.content_part.done

Событие сервера response.content_part.done возвращается при выполнении потоковой передачи части содержимого в элементе сообщения помощника.

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

Структура событий

{
  "type": "response.content_part.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": "Hello! I'm doing well, thank you for asking."
  }
}

Свойства

response.text.delta

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

Структура событий

{
  "type": "response.text.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm"
}

Свойства

response.text.done

Отправляется после завершения создания текстового содержимого.

Структура событий

{
  "type": "response.text.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

Свойства

response.audio.delta

Потоковая передача звукового содержимого из модели. Звук предоставляется в виде данных в кодировке Base64.

Структура событий

{
  "type": "response.audio.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

Свойства

response.audio.done

Отправляется после завершения создания звукового содержимого.

Структура событий

{
  "type": "response.audio.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Свойства

response.audio_transcript.delta

Потоковая расшифровка созданного звукового содержимого.

Структура событий

{
  "type": "response.audio_transcript.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm doing"
}

Свойства

response.audio_transcript.done

Отправляется после завершения создания транскрибирования звука.

Структура событий

{
  "type": "response.audio_transcript.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

Свойства

conversation.item.input_audio_transcription.completed

Событие сервера conversation.item.input_audio_transcription.completed является результатом транскрибирования звука для речи, записанной в буфер звука.

Транскрибирование начинается, когда входной звуковой буфер фиксируется клиентом или сервером (в server_vad режиме). Транскрибирование выполняется асинхронно с созданием ответа, поэтому это событие может происходить до или после событий отклика.

Модели API реального времени принимают звук в собственном коде, поэтому входные транскрибирование — это отдельный процесс, выполняемый в отдельной модели распознавания речи, например whisper-1. Таким образом, расшифровка может несколько отличаться от интерпретации модели и должна рассматриваться как грубое руководство.

Структура событий

{
  "type": "conversation.item.input_audio_transcription.completed",
  "item_id": "<item_id>",
  "content_index": 0,
  "transcript": "<transcript>"
}

Свойства

conversation.item.input_audio_transcription.delta

Событие сервера conversation.item.input_audio_transcription.delta возвращается при настройке входного транскрибирования звука, а запрос транскрибирования для сообщения пользователя выполняется. Это событие предоставляет частичные результаты транскрибирования по мере их доступности.

Структура событий

{
  "type": "conversation.item.input_audio_transcription.delta",
  "item_id": "<item_id>",
  "content_index": 0,
  "delta": "<delta>"
}

Свойства

conversation.item.input_audio_transcription.failed

Событие сервера conversation.item.input_audio_transcription.failed возвращается при настройке входного транскрибирования звука, а запрос транскрибирования для сообщения пользователя завершился ошибкой. Это событие отличается от других error событий, чтобы клиент смог идентифицировать связанный элемент.

Структура событий

{
  "type": "conversation.item.input_audio_transcription.failed",
  "item_id": "<item_id>",
  "content_index": 0,
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

Свойства

Свойства ошибки

response.animation_blendshapes.delta

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

Структура событий

{
  "type": "response.animation_blendshapes.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "frame_index": 0,
  "frames": [
    [0.0, 0.1, 0.2, ..., 1.0]
    ...
  ]
}

Свойства

response.animation_blendshapes.done

Событие сервера response.animation_blendshapes.done возвращается, когда модель завершит создание анимации смешает данные в ответе.

Структура событий

{
  "type": "response.animation_blendshapes.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
}

Свойства

response.audio_timestamp.delta

Событие сервера response.audio_timestamp.delta возвращается, когда модель создает данные метки времени звука в рамках ответа. Это событие предоставляет добавочные данные метки времени для выравнивания выходного звука и текста по мере его доступности.

Структура событий

{
  "type": "response.audio_timestamp.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "audio_duration_ms": 500,
  "text": "Hello",
  "timestamp_type": "word"
}

Свойства

response.audio_timestamp.done

Отправляется после завершения создания метки времени звука.

Структура событий

{
  "type": "response.audio_timestamp.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Свойства

response.animation_viseme.delta

Событие сервера response.animation_viseme.delta возвращается при создании данных анимации viseme в ответе. Это событие предоставляет добавочные данные viseme по мере его доступности.

Структура событий

{
  "type": "response.animation_viseme.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "viseme_id": 1
}

Свойства

response.animation_viseme.done

Событие сервера response.animation_viseme.done возвращается, когда модель завершит создание данных viseme анимации в ответе.

Структура событий

{
  "type": "response.animation_viseme.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Свойства

Событие сервера response.animation_viseme.delta возвращается при создании данных анимации viseme в ответе. Это событие предоставляет добавочные данные viseme по мере его доступности.

ошибка

Событие сервера error возвращается при возникновении ошибки, которая может быть проблемой клиента или проблемой сервера. Большинство ошибок можно восстановить, и сеанс остается открытым.

Структура событий

{
  "type": "error",
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>",
    "event_id": "<event_id>"
  }
}

Свойства

Свойства ошибки

input_audio_buffer.cleared

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

Структура событий

{
  "type": "input_audio_buffer.cleared"
}

Свойства

input_audio_buffer.committed

Событие сервера input_audio_buffer.committed возвращается, когда входной звуковой буфер фиксируется клиентом или автоматически в режиме VAD сервера. Это item_id свойство является идентификатором созданного элемента пользовательского сообщения. Таким образом, conversation.item.created событие также отправляется клиенту.

Структура событий

{
  "type": "input_audio_buffer.committed",
  "previous_item_id": "<previous_item_id>",
  "item_id": "<item_id>"
}

Свойства

input_audio_buffer.speech_started

Событие сервера input_audio_buffer.speech_started возвращается в server_vad режиме, когда речь обнаруживается в звуковом буфере. Это событие может произойти при добавлении звука в буфер (если речь еще не обнаружена).

Клиент должен ожидать получения события при остановке input_audio_buffer.speech_stopped речи. Это item_id свойство является идентификатором элемента сообщения пользователя, созданного при остановке речи. Он item_id также включен в input_audio_buffer.speech_stopped событие, если клиент вручную не фиксирует звуковой буфер во время активации VAD.

Структура событий

{
  "type": "input_audio_buffer.speech_started",
  "audio_start_ms": 0,
  "item_id": "<item_id>"
}

Свойства

input_audio_buffer.speech_остановлено

Событие сервера input_audio_buffer.speech_stopped возвращается в server_vad режиме, когда сервер обнаруживает конец речи в звуковом буфере.

Сервер также отправляет conversation.item.created событие с элементом сообщения пользователя, созданным из звукового буфера.

Структура событий

{
  "type": "input_audio_buffer.speech_stopped",
  "audio_end_ms": 0,
  "item_id": "<item_id>"
}

Свойства

rate_limits.обновлено

Событие сервера rate_limits.updated создается в начале ответа, чтобы указать обновленные ограничения скорости.

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

Структура событий

{
  "type": "rate_limits.updated",
  "rate_limits": [
    {
      "name": "<name>",
      "limit": 0,
      "remaining": 0,
      "reset_seconds": 0
    }
  ]
}

Свойства

response.audio.delta

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

Структура событий

{
  "type": "response.audio.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Свойства

response.audio.done

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

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

Структура событий

{
  "type": "response.audio.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0
}

Свойства

response.audio_transcript.delta

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

Структура событий

{
  "type": "response.audio_transcript.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Свойства

response.audio_transcript.done

Событие сервера response.audio_transcript.done возвращается при выполнении потоковой передачи данных, созданной моделью.

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

Структура событий

{
  "type": "response.audio_transcript.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "transcript": "<transcript>"
}

Свойства

response.function_call_arguments.delta

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

Структура событий

{
  "type": "response.function_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "delta": "<delta>"
}

Свойства

response.function_call_arguments.done

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

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

Структура событий

{
  "type": "response.function_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "arguments": "<arguments>"
}

Свойства

mcp_list_tools.in_progress

Событие сервера mcp_list_tools.in_progress возвращается при запуске службы перечисления доступных средств с сервера mcp.

Структура событий

{
  "type": "mcp_list_tools.in_progress",
  "item_id": "<mcp_list_tools_item_id>"
}

Свойства

mcp_list_tools.completed

Событие сервера mcp_list_tools.completed возвращается, когда служба завершает перечисление доступных средств с сервера mcp.

Структура событий

{
  "type": "mcp_list_tools.completed",
  "item_id": "<mcp_list_tools_item_id>"
}

Свойства

mcp_list_tools.failed

Событие сервера mcp_list_tools.failed возвращается, когда служба не может перечислить доступные средства с сервера mcp.

Структура событий

{
  "type": "mcp_list_tools.failed",
  "item_id": "<mcp_list_tools_item_id>"
}

Свойства

response.mcp_call_arguments.delta

Событие сервера response.mcp_call_arguments.delta возвращается при обновлении аргументов вызова средства mcp, созданного моделью.

Структура событий

{
  "type": "response.mcp_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "delta": "<delta>"
}

Свойства

response.mcp_call_arguments.done

Событие сервера response.mcp_call_arguments.done возвращается при выполнении потоковой передачи аргументов вызова средства mcp, созданного моделью.

Структура событий

{
  "type": "response.mcp_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "arguments": "<arguments>"
}

Свойства

response.mcp_call.in_progress

Событие сервера response.mcp_call.in_progress возвращается при запуске обработки вызова средства MCP.

Структура событий

{
  "type": "response.mcp_call.in_progress",
  "item_id": "<item_id>",
  "output_index": 0
}

Свойства

response.mcp_call.completed

Событие сервера response.mcp_call.completed возвращается при успешном завершении вызова средства MCP.

Структура событий

{
  "type": "response.mcp_call.completed",
  "item_id": "<item_id>",
  "output_index": 0
}

Свойства

response.mcp_call.failed

Событие сервера response.mcp_call.failed возвращается при сбое вызова средства MCP.

Структура событий

{
  "type": "response.mcp_call.failed",
  "item_id": "<item_id>",
  "output_index": 0
}

Свойства

response.output_item.added

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

Структура событий

{
  "type": "response.output_item.added",
  "response_id": "<response_id>",
  "output_index": 0
}

Свойства

response.output_item.done

Событие сервера response.output_item.done возвращается при выполнении потоковой передачи элемента.

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

Структура событий

{
  "type": "response.output_item.done",
  "response_id": "<response_id>",
  "output_index": 0
}

Свойства

response.text.delta

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

Структура событий

{
  "type": "response.text.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Свойства

response.text.done

Событие сервера response.text.done возвращается при выполнении потоковой передачи созданного моделью текста. Текст соответствует text части содержимого элемента сообщения помощника.

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

Структура событий

{
  "type": "response.text.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "text": "<text>"
}

Свойства

Components

Форматы звука

RealtimeAudioFormat

Базовый формат звука, используемый для входного звука.

Допустимые значения:

• pcm16 — 16-разрядный формат звука PCM
• g711_ulaw - Формат звука μ-права G.711
• g711_alaw — Аудиоформат G.711 A-law

RealtimeOutputAudioFormat

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

Допустимые значения:

• pcm16 — 16-разрядный звуковой формат PCM по умолчанию (24 кГц)
• pcm16_8000hz — 16-разрядный аудиоформат PCM с частотой выборки 8 кГц
• pcm16_16000hz — 16-разрядный аудиоформат PCM с частотой выборки 16 кГц
• g711_ulaw - Аудиоформат G.711 μ (mu-law) в частоте выборки 8 кГц
• g711_alaw — Аудиоформат G.711 A-law с частотой выборки 8 кГц

RealtimeAudioInputTranscriptionSettings

Конфигурация входного транскрибирования звука.

RealtimeInputAudioNoiseReductionSettings

Это может быть:

• Объект RealtimeOpenAINoiseReduction
• Объект RealtimeAzureDeepNoiseSuppression

RealtimeOpenAINoiseReduction

Конфигурация уменьшения шума OpenAI с явным полем типа, доступной только для gpt-realtime моделей и gpt-realtime-mini моделей.

RealtimeAzureDeepNoiseSuppression

Настройка для уменьшения шума входного звука.

RealtimeInputAudioEchoCancellationSettings

Конфигурация отмены эхо для обработки звука на стороне сервера.

Конфигурация голосовой связи

RealtimeVoice

Объединение всех поддерживаемых конфигураций голосовой связи.

Это может быть:

• Объект RealtimeOpenAIVoice
• Объект RealtimeAzureVoice

RealtimeOpenAIVoice

Конфигурация голосовой связи OpenAI с явным полем типа.

RealtimeAzureVoice

База конфигураций голосовой связи Azure. Это дискриминируемое объединение с различными типами:

RealtimeAzureCustomVoice

Настраиваемая конфигурация голосовой связи Azure (предпочтительна для пользовательских голосов).

Пример:

{
  "type": "azure-custom",
  "name": "my-custom-voice",
  "endpoint_id": "12345678-1234-1234-1234-123456789012",
  "temperature": 0.7,
  "style": "cheerful",
  "locale": "en-US"
}

RealtimeAzureStandardVoice

Стандартная конфигурация голосовой связи Azure.

RealtimeAzurePersonalVoice

Конфигурация личного голоса Azure.

Обнаружение поворота

RealtimeTurnDetection

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

RealtimeServerVAD

Базовое обнаружение поворота на основе VAD.

RealtimeOpenAISemanticVAD

Семантическая конфигурация VAD OpenAI, которая использует модель для определения завершения речи пользователя. Доступно только для gpt-realtime моделей и gpt-realtime-mini моделей.

RealtimeAzureSemanticVAD

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

RealtimeAzureSemanticVADMultilingual

Семантическое VAD Azure (вариант по умолчанию).

RealtimeEOUDetection

Конечное высказывание Azure (EOU) может указывать, когда конечный пользователь перестал говорить, позволяя естественным паузам. Обнаружение конца высказывания может значительно сократить преждевременные сигналы конца реплики, не добавляя заметной задержки.

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

RealtimeAvatarConfig

Настройка потоковой передачи аватара и поведения.

RealtimeIceServer

Конфигурация сервера ICE для согласования подключений WebRTC.

RealtimeVideoParams

Параметры потоковой передачи видео для аватара.

RealtimeVideoCrop

Определение прямоугольника обрезки видео.

RealtimeVideoResolution

Спецификация разрешения видео.

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

RealtimeAnimation

Конфигурация выходных данных анимации, включая смешивания и виземы.

RealtimeAnimationOutputType

Типы данных анимации для вывода.

Допустимые значения:

• blendshapes — данные о смешиваниях лиц
• viseme_id — Данные идентификатора Viseme

Конфигурация сеанса

RealtimeRequestSession

Объект конфигурации сеанса, используемый в session.update событиях.

RealtimeModality

Поддерживаемые модальности сеанса.

Допустимые значения:

• text — входные и выходные данные текста
• audio — входные и выходные данные звука
• animation — выходные данные анимации
• avatar — выходные данные видео аватара

RealtimeAudioTimestampType

Типы меток времени вывода, поддерживаемые в содержимом звукового ответа.

Допустимые значения:

• word — метки времени на слово в выходном звуке

Настройка средства

Мы поддерживаем два типа инструментов: вызов функций и инструменты MCP, которые позволяют подключаться к серверу mcp.

RealtimeTool

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

RealtimeToolChoice

Стратегия выбора инструментов.

Это может быть:

• "auto" — Пусть модель выбирается
• "none" — Не используйте средства
• "required" — должен использовать средство
• { "type": "function", "name": "function_name" } — Использование конкретной функции

MCPTool

Настройка средства MCP.

RealtimeConversationResponseItem

Это тип объединения, который может быть одним из следующих типов:

RealtimeConversationUserMessageItem

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

RealtimeConversationAssistantMessageItem

Элемент сообщения помощника.

RealtimeConversationSystemMessageItem

Элемент системного сообщения.

RealtimeConversationFunctionCallItem

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

RealtimeConversationFunctionCallOutputItem

Элемент ответа вызова функции.

RealtimeConversationMCPListToolsItem

Элемент ответа средств списка MCP.

RealtimeConversationMCPCallItem

Элемент ответа на вызов MCP.

RealtimeConversationMCPApprovalRequestItem

Элемент запроса на утверждение MCP.

RealtimeItemStatus

Состояние элементов беседы.

Допустимые значения:

• in_progress - В настоящее время обрабатывается
• completed — успешно завершено
• incomplete — неполный (прерывание или сбой)

RealtimeContentPart

Часть содержимого в сообщении.

RealtimeInputTextContentPart

Часть текстового содержимого.

RealtimeOutputTextContentPart

Часть текстового содержимого.

RealtimeInputAudioContentPart

Часть звукового содержимого.

RealtimeOutputAudioContentPart

Часть звукового содержимого.

Объекты ответа

RealtimeResponse

Объект ответа, представляющий ответ на вывод модели.

RealtimeResponseStatus

Значения состояния ответа.

Допустимые значения:

• in_progress — создается ответ
• completed — ответ успешно завершен
• cancelled - Ответ был отменен
• incomplete — неполный ответ (прерванный)
• failed — сбой ответа с ошибкой

RealtimeUsage

Статистика использования маркеров.

TokenDetails

Подробные сведения об использовании маркеров.

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

RealtimeErrorDetails

Объект сведений об ошибках.

RealtimeConversationRequestItem

Объект используется RealtimeConversationRequestItem для создания нового элемента в беседе с помощью события conversation.item.create .

Это тип объединения, который может быть одним из следующих типов:

RealtimeSystemMessageItem

Элемент системного сообщения.

RealtimeUserMessageItem

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

RealtimeAssistantMessageItem

Элемент сообщения помощника.

RealtimeFunctionCallItem

Элемент вызова функции.

RealtimeFunctionCallOutputItem

Выходной элемент вызова функции.

RealtimeMCPApprovalResponseItem

Элемент ответа на утверждение MCP.

RealtimeFunctionTool

Определение средства функции, используемого конечной точкой реального времени.

RealtimeItemStatus

Допустимые значения:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

Объект RealtimeResponseSession представляет сеанс в API Реального времени. Он используется в некоторых событиях сервера, таких как:

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Связанные ресурсы

• Попробуйте быстрое начало работы с Voice live
• Попробуйте Краткое руководство по голосовым живым агентам
• Дополнительные сведения об использовании API голосовой трансляции