Справочник по API голосовой трансляции 2026-01-01-preview (предварительная версия)

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

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

Key Features

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

Client Events

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

session.update

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

Event Structure

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

Properties

Пример с пользовательским голосом 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.avatar.connect

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

Event Structure

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

Properties

input_audio_buffer.append

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

Event Structure

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

Properties

input_audio_buffer.commit

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

Event Structure

{
  "type": "input_audio_buffer.commit"
}

Properties

input_audio_buffer.clear

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

Event Structure

{
  "type": "input_audio_buffer.clear"
}

Properties

conversation.item.create

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

Event Structure

{
  "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?"
      }
    ]
  }
}

Properties

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

{
  "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_output",
    "call_id": "call_123",
    "output": "{\"location\": \"San Francisco\", \"temperature\": \"70\"}"
  }
}

Пример ответа на утверждение MCP

{
  "type": "conversation.item.create",
  "item": {
    "type": "mcp_approval_response",
    "approval_request_id": "mcp_approval_req_456",
    "approve": true,
  }
}

conversation.item.retrieve

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

Event Structure

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

Properties

conversation.item.truncate

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

Event Structure

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

Properties

conversation.item.delete

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

Event Structure

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

Properties

response.create

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

Event Structure

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

Properties

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

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

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

В некоторых сценариях может потребоваться создать звуковой ответ для предопределенного текста вместо создания текстового ответа модели. pre_generated_assistant_message Используйте параметр в сообщенииresponse.create. В поле можно включить только одну текстовую content запись.

{
  "type": "response.create",
  "response": {
    "pre_generated_assistant_message": {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "repeat what I say"
        }
      ]
    }
  }
}

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

response.cancel

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

Event Structure

{
  "type": "response.cancel"
}

Properties

input_audio_buffer.append

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

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

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

Event structure

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

Properties

input_audio_buffer.clear

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

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

Event structure

{
  "type": "input_audio_buffer.clear"
}

Properties

input_audio_buffer.commit

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

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

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

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

Event structure

{
  "type": "input_audio_buffer.commit"
}

Properties

Server Events

API Voice Live отправляет следующие события сервера для обмена данными о состоянии, ответах и данных клиенту:

session.created

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

Event Structure

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

Properties

session.updated

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

Event Structure

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

Properties

session.avatar.connecting

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

Event Structure

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

Properties

conversation.item.created

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

Event Structure

{
  "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?"
      }
    ]
  }
}

Properties

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

{
  "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 элемент беседы.

Event Structure

{
  "type": "conversation.item.retrieved",
  "item": {
    "id": "item_ABC123",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
      }
    ]
  }
}

Properties

conversation.item.truncated

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

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

Event structure

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

Properties

conversation.item.deleted

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

Event Structure

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

Properties

response.created

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

Event Structure

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

Properties

response.done

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

Event Structure

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

Properties

response.output_item.added

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

Event Structure

{
  "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": []
  }
}

Properties

response.output_item.done

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

Event Structure

{
  "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."
      }
    ]
  }
}

Properties

response.content_part.added

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

Event Structure

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

Properties

response.content_part.done

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

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

Event Structure

{
  "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."
  }
}

Properties

response.text.delta

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

Event Structure

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

Properties

response.text.done

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

Event Structure

{
  "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?"
}

Properties

response.audio.delta

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

Event Structure

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

Properties

response.audio.done

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

Event Structure

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

Properties

response.audio_transcript.delta

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

Event Structure

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

Properties

response.audio_transcript.done

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

Event Structure

{
  "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?"
}

Properties

conversation.item.input_audio_transcription.completed

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

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

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

Event structure

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

Properties

conversation.item.input_audio_transcription.delta

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

Event structure

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

Properties

conversation.item.input_audio_transcription.failed

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

Event structure

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

Properties

Error properties

response.animation_blendshapes.delta

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

Event structure

{
  "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]
    ...
  ]
}

Properties

response.animation_blendshapes.done

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

Event structure

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

Properties

response.audio_timestamp.delta

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

Event structure

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

Properties

response.audio_timestamp.done

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

Event Structure

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

Properties

response.animation_viseme.delta

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

Event Structure

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

Properties

response.animation_viseme.done

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

Event Structure

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

Properties

error

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

Event structure

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

Properties

Error properties

warning

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

Event structure

{
  "type": "warning",
  "warning": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

Properties

Warning properties

input_audio_buffer.cleared

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

Event structure

{
  "type": "input_audio_buffer.cleared"
}

Properties

input_audio_buffer.committed

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

Event structure

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

Properties

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.

Event structure

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

Properties

input_audio_buffer.speech_stopped

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

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

Event structure

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

Properties

rate_limits.updated

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

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

Event structure

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

Properties

response.audio.delta

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

Event structure

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

Properties

response.audio.done

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

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

Event structure

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

Properties

response.audio_transcript.delta

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

Event structure

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

Properties

response.audio_transcript.done

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

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

Event structure

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

Properties

response.function_call_arguments.delta

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

Event structure

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

Properties

response.function_call_arguments.done

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

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

Event structure

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

Properties

mcp_list_tools.in_progress

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

Event structure

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

Properties

mcp_list_tools.completed

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

Event structure

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

Properties

mcp_list_tools.failed

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

Event structure

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

Properties

response.mcp_call_arguments.delta

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

Event structure

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

Properties

response.mcp_call_arguments.done

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

Event structure

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

Properties

response.mcp_call.in_progress

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

Event structure

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

Properties

response.mcp_call.completed

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

Event structure

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

Properties

response.mcp_call.failed

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

Event structure

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

Properties

response.foundry_agent_call_arguments.delta

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

Event structure

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

Properties

response.foundry_agent_call_arguments.done

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

Event structure

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

Properties

response.foundry_agent_call.in_progress

Событие сервера response.foundry_agent_call.in_progress возвращается при запуске обработки вызова агента foundry.

Event structure

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

Properties

response.foundry_agent_call.completed

Событие сервера response.foundry_agent_call.completed возвращается при успешном выполнении вызова агента foundry.

Event structure

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

Properties

response.foundry_agent_call.failed

Событие сервера response.foundry_agent_call.failed возвращается при сбое вызова агента foundry.

Event structure

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

Properties

response.output_item.added

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

Event structure

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

Properties

response.output_item.done

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

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

Event structure

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

Properties

response.text.delta

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

Event structure

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

Properties

response.text.done

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

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

Event structure

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

Properties

Components

Audio Formats

RealtimeAudioFormat

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

Allowed Values:

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

RealtimeOutputAudioFormat

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

Allowed Values:

• 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

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

Voice Configuration

RealtimeVoice

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

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

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

RealtimeOpenAIVoice

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

RealtimeAzureVoice

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

RealtimeAzureStandardVoice

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

RealtimeAzureCustomVoice

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

Example:

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

RealtimeAzurePersonalVoice

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

Turn Detection

RealtimeTurnDetection

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

RealtimeServerVAD

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

RealtimeOpenAISemanticVAD

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

RealtimeAzureSemanticVAD

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

RealtimeAzureSemanticVADMultilingual

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

RealtimeEOUDetection

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

Avatar Configuration

RealtimeAvatarConfig

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

RealtimeIceServer

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

RealtimeVideoParams

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

RealtimeVideoCrop

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

RealtimeVideoResolution

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

RealtimeVideoBackground

Конфигурация фона видео. Можно задать только один или image_urlcolor один из них.

RealtimeAvatarScene

Настройка уровня масштабирования аватара, положения, поворота и амплитуды перемещения в видеокадре.

Animation Configuration

RealtimeAnimation

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

RealtimeAnimationOutputType

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

Allowed Values:

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

Session Configuration

RealtimeRequestSession

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

RealtimeModality

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

Allowed Values:

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

RealtimeAudioTimestampType

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

Allowed Values:

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

ReasoningEffort

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

Allowed Values:

• none - Нет причинных усилий
• minimal - Минимальные усилия по рассуждениям
• low - Низкая причина усилий - быстрее ответы с меньшими причинами
• medium - Средние причины усилий - баланс между скоростью и глубиной рассуждений
• high - Высокая причина усилий - более тщательное обоснование, может занять больше времени
• xhigh - Дополнительная высокая причина усилий - максимальная глубина рассудка

Tool Configuration

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

RealtimeTool

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

RealtimeToolChoice

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

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

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

MCPTool

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

FoundryAgentTool

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

Example:

{
  "instructions": "You are a helpful assistant. Please respond with a short message like 'working on this' before calling the agent tool.",
  "tools": [
    {
      "type": "foundry_agent",
      "agent_name": "customer-service-agent",
      "agent_version": "2",
      "project_name": "my-foundry-project",
      "description": "A helpful agent that can search online information and handle complex customer requests"
    }
  ]
}

Конфигурация промежуточного ответа

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

InterimResponseConfig

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

• StaticInterimResponseConfig — предварительно созданные промежуточные ответы, выбранные из предопределенного списка.
• LlmInterimResponseConfig — промежуточные ответы, созданные LLM.

StaticInterimResponseConfig

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

Example:

{
  "session": {
    "interim-response": {
      "type": "static-interim-response",
      "triggers": ["latency", "tool"],
      "latency_threshold_ms": 1500,
      "texts": [
        "Let me think about that...",
        "One moment please...",
        "Working on that for you..."
      ]
    }
  }
}

LlmInterimResponseConfig

Конфигурация для генерации промежуточного отклика на основе LLM. Использует LLM для генерации контекстно-ориентированных промежуточных ответов при выполнении любого условия триггера.

Example:

{
  "session": {
    "interim-response": {
      "type": "llm-interim-response",
      "triggers": ["tool"],
      "latency_threshold_ms": 2000,
      "model": "gpt-4.1-mini",
      "instructions": "Generate a brief, friendly acknowledgment that you're working on the user's request.",
      "max_completion_tokens": 30
    }
  }
}

InterimResponseTrigger

Триггеры, которые могут активировать промежуточную генерацию реакции.

Allowed Values:

• latency — активация промежуточного ответа при превышении порогового значения задержки ответа
• tool — активируйте промежуточный ответ при выполнении вызова средства

RealtimeConversationResponseItem

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

RealtimeConversationUserMessageItem

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

RealtimeConversationAssistantMessageItem

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

RealtimeConversationSystemMessageItem

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

RealtimeConversationFunctionCallItem

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

RealtimeConversationFunctionCallOutputItem

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

RealtimeConversationMCPListToolsItem

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

RealtimeConversationMCPCallItem

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

RealtimeConversationMCPApprovalRequestItem

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

RealtimeConversationFoundryAgentCallItem

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

RealtimeItemStatus

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

Allowed Values:

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

RealtimeContentPart

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

RealtimeInputTextContentPart

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

RealtimeOutputTextContentPart

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

RealtimeInputAudioContentPart

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

RealtimeOutputAudioContentPart

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

Response Objects

RealtimeResponse

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

RealtimeResponseStatus

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

Allowed Values:

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

RealtimeUsage

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

TokenDetails

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

Error Handling

RealtimeErrorDetails

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

RealtimeConversationRequestItem

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

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

RealtimeSystemMessageItem

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

RealtimeUserMessageItem

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

RealtimeAssistantMessageItem

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

RealtimeFunctionCallItem

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

RealtimeFunctionCallOutputItem

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

RealtimeMCPApprovalResponseItem

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

RealtimeFunctionTool

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

RealtimeItemStatus

Allowed Values:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

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

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Related Resources

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