OpenAI 创建兼容版 Realtime 会话

译注：本页原文参数表与文末示例使用不同的会话字段结构，包括 modalities 与 output_modalities 等；请求表还列出了描述为返回值的 client_secret。相关差异保留待核，不能将示例字段直接套用于其他 Realtime 接口。

创建会话

post /realtime/sessions

创建供客户端应用使用的临时 API 令牌，用于 Realtime API。会话参数与 session.update 客户端事件中可配置的参数相同。

响应包含会话对象和 client_secret 字段，其中包含 可用于浏览器客户端身份验证的临时 API 令牌， 用于访问 Realtime API。

返回创建的 Realtime 会话对象以及临时密钥。

请求体参数

内容类型：application/json

• client_secret: object { expires_at, value }

API 返回的临时密钥。

• expires_at: integer

令牌过期的时间戳。目前所有令牌均在 一分钟后过期。

format: unixtime

• value: string

供客户端环境验证连接身份的临时密钥， 用于 Realtime API。客户端应使用该临时密钥。 标准 API 令牌仅供服务端使用。

• input_audio_format: optional string

输入音频格式，可选 pcm16、g711_ulaw 或 g711_alaw。

• input_audio_transcription: optional object { model }

输入音频转录配置，默认关闭；开启后可以 设为 null 再次关闭。输入音频转录不是模型的原生处理过程， 因为模型直接处理音频。转录以 异步方式执行，只能作为内容的大致参考， 不能视为模型实际理解内容的表示。

• model: optional string

转录使用的模型。

• instructions: optional string

模型调用前添加的默认系统指令，即系统消息。此字段允许客户端引导模型生成期望的响应。可指定内容与格式，例如“极其简洁”“态度友好”“以下是优质响应示例”，也可指定音频表现，例如“说快一点”“让声音带有情感”“经常笑”。模型不保证遵循这些指令，但它们能引导模型表现出期望的行为。 注意：未设置此字段时，服务器会使用默认指令；会话开始时的 session.created 事件中可以查看这些指令。

• max_response_output_tokens: optional number or "inf"

单次助手响应的最大输出词元数， 包括工具调用。提供 1–4096 之间的整数可 限制输出词元数，或使用 inf 表示给定模型 可用的最大词元数。默认为 inf。

• number

• "inf"

• "inf"

• modalities: optional array of "text" or "audio"

模型可用于响应的模态集合。如需禁用音频， 设为 ["text"]。

• "text"

• "audio"

• output_audio_format: optional string

输出音频格式，可选 pcm16、g711_ulaw 或 g711_alaw。

• prompt: optional ResponsePrompt or null

对提示词模板及其变量的引用。 了解更多。

• id: string

要使用的提示词模板的唯一标识。

• variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile] or null

可选的值映射，用于替换提示词中的 变量。替换值可以是字符串，也可以是其他 Responses 输入类型，例如图像或文件。

• string

• ResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

• text: string

输入模型的文本。

• type: "input_text" (default: "input_text")

输入条目类型，固定为 input_text。

• "input_text"

• prompt_cache_breakpoint: optional object { mode, ttl }

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求中的 prompt_cache_options.ttl；该边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为 explicit。

• "explicit"

• ttl: optional "30m" or "12h"

此缓存断点的最短存续时间，默认为请求的 TTL。

• "30m"

• "12h"

• ResponseInputImage object { detail, type, file_id, 2 more }

输入模型的图像。参阅图像输入。

• detail: ImageDetail

发送给模型的图像细节级别，可选 high、low、auto 或 original，默认为 auto。

• "low"

• "high"

• "auto"

• "original"

• type: "input_image" (default: "input_image")

输入条目类型，固定为 input_image。

• "input_image"

• file_id: optional string or null

要发送给模型的文件 ID。

• image_url: optional string or null

要发送给模型的图像 URL，可以是完整 URL，或包含 Base64 编码图像的 data URL。

format: uri

• prompt_cache_breakpoint: optional object { mode, ttl }

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求中的 prompt_cache_options.ttl；该边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为 explicit。

• "explicit"

• ttl: optional "30m" or "12h"

此缓存断点的最短存续时间，默认为请求的 TTL。

• "30m"

• "12h"

• ResponseInputFile object { type, detail, file_data, 4 more }

输入模型的文件。

• type: "input_file" (default: "input_file")

输入条目类型，固定为 input_file。

• "input_file"

• detail: optional "auto" or "low" or "high"

发送给模型的文件细节级别。使用 auto 由系统选择；对于 GPT-5.6 及后续模型，auto 使用高质量渲染，可能增加输入词元用量。使用 low 进行成本较低的渲染，或使用 high 以更高质量渲染文件。默认为 auto。

• "auto"

• "low"

• "high"

• file_data: optional string

要发送给模型的文件内容。

• file_id: optional string or null

要发送给模型的文件 ID。

• file_url: optional string

要发送给模型的文件 URL。

format: uri

• filename: optional string

要发送给模型的文件名。

• prompt_cache_breakpoint: optional object { mode, ttl }

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求中的 prompt_cache_options.ttl；该边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为 explicit。

• "explicit"

• ttl: optional "30m" or "12h"

此缓存断点的最短存续时间，默认为请求的 TTL。

• "30m"

• "12h"

• version: optional string or null

提示词模板的可选版本。

• speed: optional number (default: 1)

模型语音响应的速度，默认为 1.0，最小值为 0.25， 最大值为 1.5。此值只能在模型轮次 之间更改，不能在响应进行中更改。

minimum: 0.25, maximum: 1.5

• temperature: optional number

模型采样温度，限制在 [0.6, 1.2]，默认为 0.8。

• tool_choice: optional string

模型选择工具的方式，可选 auto、none、required，或 指定一个函数。

• tools: optional array of object { description, name, parameters, type }

模型可用的工具（函数）。

• description: optional string

函数描述，包括何时以及如何 调用该函数的指导，以及调用时应向用户说明什么 内容，如需说明。

• name: optional string

函数名称。

• parameters: optional unknown

以 JSON Schema 描述的函数参数。

• type: optional "function"

工具类型，即 function。

• "function"

• tracing: optional "auto" or TracingConfiguration { group_id, metadata, workflow_name }

追踪配置选项。设为 null 可禁用追踪。一旦 为会话启用追踪，就不能修改配置。

auto 会使用默认的工作流名称、分组 ID 和元数据 为会话创建追踪记录。

• "auto"

会话的默认追踪模式。

• "auto"

• TracingConfiguration object { group_id, metadata, workflow_name }

追踪的细粒度配置。

• group_id: optional string

要附加到此追踪记录的分组 ID，以便在追踪控制台中筛选和 在追踪控制台中分组。

• metadata: optional unknown

要附加到此追踪记录的任意元数据，以便在追踪控制台中 在追踪控制台中筛选。

• workflow_name: optional string

要附加到此追踪记录的工作流名称，用于在追踪控制台中 在追踪控制台中为追踪记录命名。

• truncation: optional RealtimeTruncation

对话词元数超过模型的输入词元上限时，会截断对话，即从最早的消息开始，将部分消息排除在模型上下文之外。对于上下文为 32k、最大输出为 4,096 个词元的模型，发生截断前最多只能在上下文中包含 28,224 个词元。

客户端可以将截断所用的最大词元数设得更低，以控制词元用量和成本。

截断会从上下文开头丢弃消息，因此会减少下一轮的缓存词元数，导致缓存失效。但客户端也可以配置截断，使保留消息的词元数不超过最大上下文大小的一定比例，从而减少后续截断次数，提高缓存命中率。

可以完全禁用截断。此时服务端不会截断；如果对话超过模型的输入词元上限，会返回错误。

• "auto" or "disabled"

会话使用的截断策略，默认为 auto。disabled 会禁用截断，在对话超过输入词元上限时报告错误。

• "auto"

• "disabled"

• RetentionRatioTruncation object { retention_ratio, type, token_limits }

对话超过输入词元上限时，保留一定比例的对话词元。这样可以将截断成本分摊到多个轮次，有助于改善缓存词元的使用情况。

• retention_ratio: number

对话超过输入词元上限时，在指令之后的对话词元中保留的比例，范围为 0.0–1.0。设为 0.8 时，持续丢弃消息，直到词元数降至允许最大值的 80%，有助于降低截断频率、提高缓存命中率。

minimum: 0, maximum: 1

• type: "retention_ratio"

使用保留比例截断策略。

• "retention_ratio"

• token_limits: optional object { post_instructions }

此截断策略可选的自定义词元上限。未提供时，使用模型的默认词元上限。

• post_instructions: optional integer

指令之后的对话允许的最大词元数，其中指令包含工具定义。例如设为 5,000，则指令之后的对话超过 5,000 个词元时发生截断。此值不能高于模型上下文窗口大小减去最大输出词元数。

minimum: 0

• turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量检测语音的开始与结束，并在用户说话结束时响应。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

判断语音结束所需的静音时长，单位为毫秒，默认 为 500 毫秒。较短的时长可加快响应， 但可能在用户短暂停顿时提前插入响应。

• threshold: optional number

VAD 激活阈值范围为 0.0–1.0，默认 0.5。 较高阈值要求更大的音量才能激活模型， 因此可能更适合嘈杂环境。

• type: optional string

话轮检测类型，目前仅支持 server_vad。

• voice: optional string or "alloy" or "ash" or "ballad" or 7 more or ID { id }

模型响应使用的音色。支持的内置音色包括 alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin 和 cedar。也可以提供包含 id 的自定义音色对象，例如 { "id": "voice_1234" }。在模型至少输出过一次音频后， 该会话期间不能再更改音色。 自定义音色须通过音频样本创建。通过文本提示词创建的音色仅适用于 Live。

• string

• "alloy" or "ash" or "ballad" or 7 more

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• ID object { id }

自定义音色引用。

• id: string

自定义音色 ID，例如 voice_1234。

返回值

• id: optional string

会话唯一标识，类似 sess_1234567890abcdef。

• audio: optional object { input, output }

会话的输入和输出音频配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• format: optional RealtimeAudioFormats

PCM 音频格式，仅支持 24kHz 采样率。

• PCMAudio object { rate, type }

PCM 音频格式，仅支持 24kHz 采样率。

• rate: optional 24000

音频采样率，固定为 24000。

• 24000

• type: optional "audio/pcm"

音频格式，固定为 audio/pcm。

• "audio/pcm"

• PCMUAudio object { type }

G.711 μ-law 格式。

• type: optional "audio/pcmu"

音频格式，固定为 audio/pcmu。

• "audio/pcmu"

• PCMAAudio object { type }

G.711 A-law 格式。

• type: optional "audio/pcma"

音频格式，固定为 audio/pcma。

• "audio/pcma"

• noise_reduction: optional object { type } or null

输入音频降噪配置。

• type: optional NoiseReductionType

降噪类型。near_field 适用于耳机等近讲麦克风，far_field 适用于笔记本或会议室等远场麦克风。

• "near_field"

• "far_field"

• transcription: optional object { keywords, language, languages, 2 more }

输入音频转录配置。

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

minItems: 1

• model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more

转录模型，可选 whisper-1、gpt-transcribe、gpt-live-transcribe、gpt-4o-mini-transcribe、gpt-4o-mini-transcribe-2025-12-15、gpt-4o-transcribe、gpt-4o-transcribe-diarize 和 gpt-realtime-whisper。

• string

• "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more

转录模型，可选 whisper-1、gpt-transcribe、gpt-live-transcribe、gpt-4o-mini-transcribe、gpt-4o-mini-transcribe-2025-12-15、gpt-4o-transcribe、gpt-4o-transcribe-diarize 和 gpt-realtime-whisper。

• "whisper-1"

• "gpt-transcribe"

• "gpt-live-transcribe"

• "gpt-4o-mini-transcribe"

• "gpt-4o-mini-transcribe-2025-12-15"

• "gpt-4o-transcribe"

• "gpt-4o-transcribe-diarize"

• "gpt-realtime-whisper"

• prompt: optional string

为输入音频转录配置的提示词（如有）。

• turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type } or null

轮次检测配置。

• prefix_padding_ms: optional integer

• silence_duration_ms: optional integer

• threshold: optional number

• type: optional string

话轮检测类型，目前仅支持 server_vad。

• output: optional object { format, speed, voice }

• format: optional RealtimeAudioFormats

PCM 音频格式，仅支持 24kHz 采样率。

• speed: optional number

• voice: optional string or "alloy" or "ash" or "ballad" or 7 more

• string

• "alloy" or "ash" or "ballad" or 7 more

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

• include: optional array of "item.input_audio_transcription.logprobs"

服务端输出中需要包含的额外字段。

• item.input_audio_transcription.logprobs：包含输入音频转录的对数概率。

• "item.input_audio_transcription.logprobs"

• instructions: optional string

模型调用前添加的默认系统指令，即系统消息。 此字段允许客户端引导模型生成期望的 响应。可指定响应内容与格式， 例如“极其简洁”“态度友好”“以下是优质 响应示例”，也可指定音频表现，例如“说快一点”“让声音带有 情感”“经常笑”。模型不保证 遵循这些指令，但它们可以引导模型表现出 期望的行为。

注意：未设置此字段时，服务器会使用 默认指令；会话开始时的 session.created 事件中 可以查看这些指令。

• max_output_tokens: optional number or "inf"

单次助手响应的最大输出词元数， 包括工具调用。提供 1–4096 之间的整数可 限制输出词元数，或使用 inf 表示给定模型 可用的最大词元数。默认为 inf。

• number

• "inf"

• "inf"

• model: optional string

此会话使用的 Realtime 模型。

• object: optional string

对象类型，固定为 realtime.session。

• output_modalities: optional array of "text" or "audio"

模型可用于响应的模态集合。如需禁用音频， 设为 ["text"]。

• "text"

• "audio"

• tool_choice: optional string

模型选择工具的方式，可选 auto、none、required，或 指定一个函数。

• tools: optional array of RealtimeFunctionTool

模型可用的工具（函数）。

• description: optional string

函数描述，包括何时以及如何 调用该函数的指导，以及调用时应向用户说明什么 内容，如需说明。

• name: optional string

函数名称。

• parameters: optional unknown

以 JSON Schema 描述的函数参数。

• type: optional "function"

工具类型，即 function。

• "function"

• tracing: optional "auto" or TracingConfiguration { group_id, metadata, workflow_name }

追踪配置选项。设为 null 可禁用追踪。一旦 为会话启用追踪，就不能修改配置。

auto 会使用默认的工作流名称、分组 ID 和元数据 为会话创建追踪记录。

• "auto"

会话的默认追踪模式。

• "auto"

• TracingConfiguration object { group_id, metadata, workflow_name }

追踪的细粒度配置。

• group_id: optional string

要附加到此追踪记录的分组 ID，以便在追踪控制台中筛选和 在追踪控制台中分组。

• metadata: optional unknown

要附加到此追踪记录的任意元数据，以便在追踪控制台中 在追踪控制台中筛选。

• workflow_name: optional string

要附加到此追踪记录的工作流名称，用于在追踪控制台中 在追踪控制台中为追踪记录命名。

• turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type } or null

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量检测语音的开始与结束，并在用户说话结束时响应。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

判断语音结束所需的静音时长，单位为毫秒，默认 为 500 毫秒。较短的时长可加快响应， 但可能在用户短暂停顿时提前插入响应。

• threshold: optional number

VAD 激活阈值范围为 0.0–1.0，默认 0.5。 较高阈值要求更大的音量才能激活模型， 因此可能更适合嘈杂环境。

• type: optional string

话轮检测类型，目前仅支持 server_vad。

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话配置或 SDP；临时密钥仅供客户端使用。
curl https://api.openai.com/v1/realtime/sessions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "client_secret": {
            "expires_at": 0,
            "value": "value"
          }
        }'

200 响应示例

{
  "id": "id",
  "audio": {
    "input": {
      "format": {
        "rate": 24000,
        "type": "audio/pcm"
      },
      "noise_reduction": {
        "type": "near_field"
      },
      "transcription": {
        "keywords": [
          "string"
        ],
        "language": "language",
        "languages": [
          "string"
        ],
        "model": "gpt-transcribe",
        "prompt": "prompt"
      },
      "turn_detection": {
        "prefix_padding_ms": 0,
        "silence_duration_ms": 0,
        "threshold": 0,
        "type": "type"
      }
    },
    "output": {
      "format": {
        "rate": 24000,
        "type": "audio/pcm"
      },
      "speed": 0,
      "voice": "ash"
    }
  },
  "expires_at": 0,
  "include": [
    "item.input_audio_transcription.logprobs"
  ],
  "instructions": "instructions",
  "max_output_tokens": "inf",
  "model": "model",
  "object": "object",
  "output_modalities": [
    "text"
  ],
  "tool_choice": "tool_choice",
  "tools": [
    {
      "description": "description",
      "name": "name",
      "parameters": {},
      "type": "function"
    }
  ],
  "tracing": "auto",
  "turn_detection": {
    "prefix_padding_ms": 0,
    "silence_duration_ms": 0,
    "threshold": 0,
    "type": "type"
  }
}

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话配置或 SDP；临时密钥仅供客户端使用。
curl -X POST https://api.openai.com/v1/realtime/sessions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-realtime",
    "modalities": ["audio", "text"],
    "instructions": "你是一名友好的助手。"
  }'

响应示例

{
  "id": "sess_001",
  "object": "realtime.session",
  "model": "gpt-realtime-2025-08-25",
  "modalities": ["audio", "text"],
  "instructions": "你是一名友好的助手。",
  "voice": "alloy",
  "input_audio_format": "pcm16",
  "output_audio_format": "pcm16",
  "input_audio_transcription": {
      "model": "whisper-1"
  },
  "turn_detection": null,
  "tools": [],
  "tool_choice": "none",
  "temperature": 0.7,
  "max_response_output_tokens": 200,
  "speed": 1.1,
  "tracing": "auto",
  "client_secret": {
    "value": "ek_abc123", 
    "expires_at": 1234567890
  }
}