一步API中文文档
  1. 接口
一步API中文文档
  • 01_人工客服
  • 02_购买地址
  • 03_base_url说明
  • 04_API key的获取和使用
  • 05_支持的模型与在线查询
  • 06_API Key余额查询
  • 07_常用工具配置教程
    • 01_Chatbox多端一键配置Claude/GPT/DeepSeek等主流模型
    • 02_JetBrains 全家桶(idea、PyCharm、WebStorm)配置教程
    • 03_Cursor配置
    • 04_Trae AI配置
    • 05_AingDesk配置(更新中)
    • 06_vscode配置(更新中)
  • 08_示例代码
    • python
      • 01_OpenAI-Python示例代码
      • 02_Claude-Python示例代码
      • 03_OpenAI-image-Python示例代码
      • 04_Gemini-Python示例代码
      • 05_Python分析文件代码示例
      • 06_Python其他示例
    • Java
      • 01_OpenAI-Java示例代码
      • 02_Claude-Java示例代码
  • 聊天接口(Chat)
    • 图片识别接口
    • 聊天接口(通用)
  • 向量生成(Embeddings)
    • 创建嵌入
  • 文生图片(Images)
    • DALL·E
  • 音频(Audio)
    • TTS文本转语音
  • 更新中
    • API的介绍及使用教程点击内涵链接
    • 常用教程合集
    • Anthropic Claude接口
    • Claude账号登录教程
  • 接口
    • Anthropic 对话格式(Messages)
    • Cohere 重排序格式(Rerank)
    • Deepseek reasoning 对话格式(类Chat Completions)
    • Jina AI 重排序格式(Rerank)
    • Midjourney 图像格式(Midjourney Proxy/Midjourney Proxy Plus)
    • OpenAI 音频格式
    • OpenAI 对话格式(Chat Completions)
    • OpenAI 嵌入格式(Embeddings)
    • OpenAI 图像格式(Image)
    • OpenAI 实时对话接口
    • OpenAI 响应格式(Responses)
    • Suno 音乐格式(Music)
    • Xinference 重排序格式(Rerank)
  1. 接口

OpenAI 实时对话接口

OpenAI 实时对话接口#

!!! info "官方文档"
OpenAI Realtime WebRTC
OpenAI Realtime WebSocket

📝 概述#

简介#

OpenAI Realtime API 提供两种连接方式:
1.
WebRTC - 适用于浏览器和移动客户端的实时音视频交互
2.
WebSocket - 适用于服务器到服务器的应用程序集成

使用场景#

实时语音对话
音视频会议
实时翻译
语音转写
实时代码生成
服务器端实时集成

主要特性#

双向音频流传输
文本和音频混合对话
函数调用支持
自动语音检测(VAD)
音频转写功能
WebSocket 服务器端集成

🔐 认证与安全#

认证方式#

1.
标准 API 密钥 (仅服务器端使用)
2.
临时令牌 (客户端使用)

临时令牌#

有效期: 1分钟
使用限制: 单个连接
获取方式: 通过服务器端 API 创建

安全建议#

永远不要在客户端暴露标准 API 密钥
使用 HTTPS/WSS 进行通信
实现适当的访问控制
监控异常活动

🔌 连接建立#

WebRTC 连接#

URL: https://yibuapi.com/v1/realtime
查询参数: model
请求头:
Authorization: Bearer EPHEMERAL_KEY
Content-Type: application/sdp

WebSocket 连接#

URL: wss://yibuapi.com/v1/realtime
查询参数: model
请求头:
Authorization: Bearer YOUR_API_KEY
OpenAI-Beta: realtime=v1

连接流程#

数据通道#

名称: oai-events
用途: 事件传输
格式: JSON

音频流#

输入: addTrack()
输出: ontrack 事件

💬 对话交互#

对话模式#

1.
纯文本对话
2.
语音对话
3.
混合对话

会话管理#

创建会话
更新会话
结束会话
会话配置

事件类型#

文本事件
音频事件
函数调用
状态更新
错误事件

⚙️ 配置选项#

音频配置#

输入格式
pcm16
g711_ulaw
g711_alaw
输出格式
pcm16
g711_ulaw
g711_alaw
语音类型
alloy
echo
shimmer

模型配置#

温度
最大输出长度
系统提示词
工具配置

VAD 配置#

阈值
静音时长
前缀填充

💡 请求示例#

WebRTC 连接 ❌#

客户端实现 (浏览器)#

服务器端实现 (Node.js)#

WebRTC 事件收发示例#

WebSocket 连接 ✅#

Node.js (ws模块)#

Python (websocket-client)#

浏览器 (标准WebSocket)#

消息收发示例#

Node.js/浏览器#
Python#

⚠️ 错误处理#

常见错误#

1.
连接错误
网络问题
认证失败
配置错误
2.
音频错误
设备权限
格式不支持
编解码问题
3.
会话错误
令牌过期
会话超时
并发限制

错误恢复#

1.
自动重连
2.
会话恢复
3.
错误重试
4.
降级处理

📝 事件参考#

通用请求头#

所有事件都需要包含以下请求头:
请求头类型说明示例值
Authorization字符串认证令牌Bearer $NEW_API_KEY
OpenAI-Beta字符串API 版本realtime=v1

客户端事件#

session.update#

更新会话的默认配置。
参数类型必需说明示例值/可选值
event_id字符串否客户端生成的事件标识符event_123
type字符串否事件类型session.update
modalities字符串数组否模型可以响应的模态类型["text", "audio"]
instructions字符串否预置到模型调用前的系统指令"Your knowledge cutoff is 2023-10..."
voice字符串否模型使用的语音类型alloy、echo、shimmer
input_audio_format字符串否输入音频格式pcm16、g711_ulaw、g711_alaw
output_audio_format字符串否输出音频格式pcm16、g711_ulaw、g711_alaw
input_audio_transcription.model字符串否用于转写的模型whisper-1
turn_detection.type字符串否语音检测类型server_vad
turn_detection.threshold数字否VAD 激活阈值(0.0-1.0)0.8
turn_detection.prefix_padding_ms整数否语音开始前包含的音频时长500
turn_detection.silence_duration_ms整数否检测语音停止的静音持续时间1000
tools数组否模型可用的工具列表[]
tool_choice字符串否模型选择工具的方式auto/none/required
temperature数字否模型采样温度0.8
max_output_tokens字符串/整数否单次响应最大token数"inf"/4096

input_audio_buffer.append#

向输入音频缓冲区追加音频数据。
参数类型必需说明示例值
event_id字符串否客户端生成的事件标识符event_456
type字符串否事件类型input_audio_buffer.append
audio字符串否Base64编码的音频数据Base64EncodedAudioData

input_audio_buffer.commit#

将缓冲区中的音频数据提交为用户消息。
参数类型必需说明示例值
event_id字符串否客户端生成的事件标识符event_789
type字符串否事件类型input_audio_buffer.commit

input_audio_buffer.clear#

清空输入音频缓冲区中的所有音频数据。
参数类型必需说明示例值
event_id字符串否客户端生成的事件标识符event_012
type字符串否事件类型input_audio_buffer.clear

conversation.item.create#

向对话中添加新的对话项。
参数类型必需说明示例值
event_id字符串否客户端生成的事件标识符event_345
type字符串否事件类型conversation.item.create
previous_item_id字符串否新对话项将插入在此ID之后null
item.id字符串否对话项的唯一标识符msg_001
item.type字符串否对话项类型message/function_call/function_call_output
item.status字符串否对话项状态completed/in_progress/incomplete
item.role字符串否消息发送者的角色user/assistant/system
item.content数组否消息内容[text/audio/transcript]
item.call_id字符串否函数调用的IDcall_001
item.name字符串否被调用的函数名称function_name
item.arguments字符串否函数调用的参数{"param": "value"}
item.output字符串否函数调用的输出结果{"result": "value"}

conversation.item.truncate#

截断助手消息中的音频内容。
参数类型必需说明示例值
event_id字符串否客户端生成的事件标识符event_678
type字符串否事件类型conversation.item.truncate
item_id字符串否要截断的助手消息项的IDmsg_002
content_index整数否要截断的内容部分的索引0
audio_end_ms整数否音频截断的结束时间点1500

conversation.item.delete#

从对话历史中删除指定的对话项。
参数类型必需说明示例值
event_id字符串否客户端生成的事件标识符event_901
type字符串否事件类型conversation.item.delete
item_id字符串否要删除的对话项的IDmsg_003

response.create#

触发响应生成。
参数类型必需说明示例值
event_id字符串否客户端生成的事件标识符event_234
type字符串否事件类型response.create
response.modalities字符串数组否响应的模态类型["text", "audio"]
response.instructions字符串否给模型的指令"Please assist the user."
response.voice字符串否模型使用的语音类型alloy/echo/shimmer
response.output_audio_format字符串否输出音频格式pcm16
response.tools数组否模型可用的工具列表["type", "name", "description"]
response.tool_choice字符串否模型选择工具的方式auto
response.temperature数字否采样温度0.7
response.max_output_tokens整数/字符串否最大输出token数150/"inf"

response.cancel#

取消正在进行中的响应生成。
参数类型必需说明示例值
event_id字符串否客户端生成的事件标识符event_567
type字符串否事件类型response.cancel

服务端事件#

error#

当发生错误时返回的事件。
参数类型必需说明示例值
event_id字符串数组否服务端事件的唯一标识符["event_890"]
type字符串否事件类型error
error.type字符串否错误类型invalid_request_error/server_error
error.code字符串否错误代码invalid_event
error.message字符串否人类可读的错误消息"The 'type' field is missing."
error.param字符串否与错误相关的参数null
error.event_id字符串否相关事件的IDevent_567

conversation.item.input_audio_transcription.completed#

当启用输入音频转写功能并且转写成功时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_2122
type字符串否事件类型conversation.item.input_audio_transcription.completed
item_id字符串否用户消息项的IDmsg_003
content_index整数否包含音频的内容部分的索引0
transcript字符串否转写的文本内容"Hello, how are you?"

conversation.item.input_audio_transcription.failed#

当配置了输入音频转写功能,但用户消息的转写请求失败时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_2324
type字符串数组否事件类型["conversation.item.input_audio_transcription.failed"]
item_id字符串否用户消息项的IDmsg_003
content_index整数否包含音频的内容部分的索引0
error.type字符串否错误类型transcription_error
error.code字符串否错误代码audio_unintelligible
error.message字符串否人类可读的错误消息"The audio could not be transcribed."
error.param字符串否与错误相关的参数null

conversation.item.truncated#

当客户端截断了之前的助手音频消息项时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_2526
type字符串否事件类型conversation.item.truncated
item_id字符串否被截断的助手消息项的IDmsg_004
content_index整数否被截断的内容部分的索引0
audio_end_ms整数否音频被截断的时间点(毫秒)1500

conversation.item.deleted#

当对话中的某个项目被删除时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_2728
type字符串否事件类型conversation.item.deleted
item_id字符串否被删除的对话项的IDmsg_005

input_audio_buffer.committed#

当音频缓冲区中的数据被提交时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_1121
type字符串否事件类型input_audio_buffer.committed
previous_item_id字符串否新对话项将插入在此ID对应的对话项之后msg_001
item_id字符串否将要创建的用户消息项的IDmsg_002

input_audio_buffer.cleared#

当客户端清空输入音频缓冲区时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_1314
type字符串否事件类型input_audio_buffer.cleared

input_audio_buffer.speech_started#

在服务器语音检测模式下,当检测到语音输入时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_1516
type字符串否事件类型input_audio_buffer.speech_started
audio_start_ms整数否从会话开始到检测到语音的毫秒数1000
item_id字符串否语音停止时将创建的用户消息项的IDmsg_003

input_audio_buffer.speech_stopped#

在服务器语音检测模式下,当检测到语音输入停止时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_1718
type字符串否事件类型input_audio_buffer.speech_stopped
audio_start_ms整数否从会话开始到检测到语音停止的毫秒数2000
item_id字符串否将要创建的用户消息项的IDmsg_003

response.created#

当创建新的响应时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_2930
type字符串否事件类型response.created
response.id字符串否响应的唯一标识符resp_001
response.object字符串否对象类型realtime.response
response.status字符串否响应的状态in_progress
response.status_details对象否状态的附加详细信息null
response.output字符串数组否响应生成的输出项列表["[]"]
response.usage对象否响应的使用统计信息null

response.done#

当响应完成流式传输时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_3132
type字符串否事件类型response.done
response.id字符串否响应的唯一标识符resp_001
response.object字符串否对象类型realtime.response
response.status字符串否响应的最终状态completed/cancelled/failed/incomplete
response.status_details对象否状态的附加详细信息null
response.output字符串数组否响应生成的输出项列表["[...]"]
response.usage.total_tokens整数否总token数50
response.usage.input_tokens整数否输入token数20
response.usage.output_tokens整数否输出token数30

response.output_item.added#

当响应生成过程中创建新的输出项时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_3334
type字符串否事件类型response.output_item.added
response_id字符串否输出项所属的响应IDresp_001
output_index字符串否输出项在响应中的索引0
item.id字符串否输出项的唯一标识符msg_007
item.object字符串否对象类型realtime.item
item.type字符串否输出项类型message/function_call/function_call_output
item.status字符串否输出项状态in_progress/completed
item.role字符串否与输出项关联的角色assistant
item.content数组否输出项的内容["type", "text", "audio", "transcript"]

response.output_item.done#

当输出项完成流式传输时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_3536
type字符串否事件类型response.output_item.done
response_id字符串否输出项所属的响应IDresp_001
output_index字符串否输出项在响应中的索引0
item.id字符串否输出项的唯一标识符msg_007
item.object字符串否对象类型realtime.item
item.type字符串否输出项类型message/function_call/function_call_output
item.status字符串否输出项的最终状态completed/incomplete
item.role字符串否与输出项关联的角色assistant
item.content数组否输出项的内容["type", "text", "audio", "transcript"]

response.content_part.added#

当响应生成过程中向助手消息项添加新的内容部分时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_3738
type字符串否事件类型response.content_part.added
response_id字符串否响应的IDresp_001
item_id字符串否添加内容部分的消息项IDmsg_007
output_index整数否输出项在响应中的索引0
content_index整数否内容部分在消息项内容数组中的索引0
part.type字符串否内容类型text/audio
part.text字符串否文本内容"Hello"
part.audio字符串否Base64编码的音频数据"base64_encoded_audio_data"
part.transcript字符串否音频的转写文本"Hello"

response.content_part.done#

当助手消息项中的内容部分完成流式传输时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_3940
type字符串否事件类型response.content_part.done
response_id字符串否响应的IDresp_001
item_id字符串否添加内容部分的消息项IDmsg_007
output_index整数否输出项在响应中的索引0
content_index整数否内容部分在消息项内容数组中的索引0
part.type字符串否内容类型text/audio
part.text字符串否文本内容"Hello"
part.audio字符串否Base64编码的音频数据"base64_encoded_audio_data"
part.transcript字符串否音频的转写文本"Hello"

response.text.delta#

当"text"类型内容部分的文本值更新时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_4142
type字符串否事件类型response.text.delta
response_id字符串否响应的IDresp_001
item_id字符串否消息项的IDmsg_007
output_index整数否输出项在响应中的索引0
content_index整数否内容部分在消息项内容数组中的索引0
delta字符串否文本增量更新内容"Sure, I can h"

response.text.done#

当"text"类型内容部分的文本流式传输完成时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_4344
type字符串否事件类型response.text.done
response_id字符串否响应的IDresp_001
item_id字符串否消息项的IDmsg_007
output_index整数否输出项在响应中的索引0
content_index整数否内容部分在消息项内容数组中的索引0
delta字符串否最终的完整文本内容"Sure, I can help with that."

response.audio_transcript.delta#

当模型生成的音频输出转写内容更新时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_4546
type字符串否事件类型response.audio_transcript.delta
response_id字符串否响应的IDresp_001
item_id字符串否消息项的IDmsg_008
output_index整数否输出项在响应中的索引0
content_index整数否内容部分在消息项内容数组中的索引0
delta字符串否转写文本的增量更新内容"Hello, how can I a"

response.audio_transcript.done#

当模型生成的音频输出转写完成流式传输时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_4748
type字符串否事件类型response.audio_transcript.done
response_id字符串否响应的IDresp_001
item_id字符串否消息项的IDmsg_008
output_index整数否输出项在响应中的索引0
content_index整数否内容部分在消息项内容数组中的索引0
transcript字符串否音频的最终完整转写文本"Hello, how can I assist you today?"

response.audio.delta#

当模型生成的音频内容更新时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_4950
type字符串否事件类型response.audio.delta
response_id字符串否响应的IDresp_001
item_id字符串否消息项的IDmsg_008
output_index整数否输出项在响应中的索引0
content_index整数否内容部分在消息项内容数组中的索引0
delta字符串否Base64编码的音频数据增量"Base64EncodedAudioDelta"

response.audio.done#

当模型生成的音频完成时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_5152
type字符串否事件类型response.audio.done
response_id字符串否响应的IDresp_001
item_id字符串否消息项的IDmsg_008
output_index整数否输出项在响应中的索引0
content_index整数否内容部分在消息项内容数组中的索引0

函数调用#

response.function_call_arguments.delta#

当模型生成的函数调用参数更新时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_5354
type字符串否事件类型response.function_call_arguments.delta
response_id字符串否响应的IDresp_002
item_id字符串否消息项的IDfc_001
output_index整数否输出项在响应中的索引0
call_id字符串否函数调用的IDcall_001
delta字符串否JSON格式的函数调用参数增量"{"location": "San""

response.function_call_arguments.done#

当模型生成的函数调用参数完成流式传输时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_5556
type字符串否事件类型response.function_call_arguments.done
response_id字符串否响应的IDresp_002
item_id字符串否消息项的IDfc_001
output_index整数否输出项在响应中的索引0
call_id字符串否函数调用的IDcall_001
arguments字符串否最终的完整函数调用参数(JSON格式)"{"location": "San Francisco"}"

其他状态更新#

rate_limits.updated#

在每个 "response.done" 事件之后触发,用于指示更新后的速率限制。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_5758
type字符串否事件类型rate_limits.updated
rate_limits对象数组否速率限制信息列表[{"name": "requests_per_min", "limit": 60, "remaining": 45, "reset_seconds": 35}]

conversation.created#

当对话创建时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_9101
type字符串否事件类型conversation.created
conversation对象否对话资源对象{"id": "conv_001", "object": "realtime.conversation"}

conversation.item.created#

当对话项创建时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_1920
type字符串否事件类型conversation.item.created
previous_item_id字符串否前一个对话项的IDmsg_002
item对象否对话项对象{"id": "msg_003", "object": "realtime.item", "type": "message", "status": "completed", "role": "user", "content": [{"type": "text", "text": "Hello"}]}

session.created#

当会话创建时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_1234
type字符串否事件类型session.created
session对象否会话对象{"id": "sess_001", "object": "realtime.session", "model": "gpt-4", "modalities": ["text", "audio"]}

session.updated#

当会话更新时返回此事件。
参数类型必需说明示例值
event_id字符串否服务端事件的唯一标识符event_5678
type字符串否事件类型session.updated
session对象否更新后的会话对象{"id": "sess_001", "object": "realtime.session", "model": "gpt-4", "modalities": ["text", "audio"]}

速率限制事件参数表#

参数类型必需说明示例值
name字符串是限制名称requests_per_min
limit整数是限制值60
remaining整数是剩余可用量45
reset_seconds整数是重置时间(秒)35

函数调用参数表#

参数类型必需说明示例值
type字符串是函数类型function
name字符串是函数名称get_weather
description字符串否函数描述Get the current weather
parameters对象是函数参数定义{"type": "object", "properties": {...}}

音频格式参数表#

参数类型说明可选值
sample_rate整数采样率8000, 16000, 24000, 44100, 48000
channels整数声道数1 (单声道), 2 (立体声)
bits_per_sample整数采样位数16 (pcm16), 8 (g711)
encoding字符串编码方式pcm16, g711_ulaw, g711_alaw

语音检测参数表#

参数类型说明默认值范围
threshold浮点数VAD 激活阈值0.50.0-1.0
prefix_padding_ms整数语音前缀填充(毫秒)5000-5000
silence_duration_ms整数静音检测时长(毫秒)1000100-10000

工具选择参数表#

参数类型说明可选值
tool_choice字符串工具选择方式auto, none, required
tools数组可用工具列表[{type, name, description, parameters}]

模型配置参数表#

参数类型说明范围/可选值默认值
temperature浮点数采样温度0.0-2.01.0
max_output_tokens整数/字符串最大输出长度1-4096/"inf""inf"
modalities字符串数组响应模态["text", "audio"]["text"]
voice字符串语音类型alloy, echo, shimmeralloy

事件通用参数表#

参数类型必需说明示例值
event_id字符串是事件的唯一标识符event_123
type字符串是事件类型session.update
timestamp整数否事件发生的时间戳(毫秒)1677649363000

会话状态参数表#

参数类型说明可选值
status字符串会话状态active, ended, error
error对象错误信息{"type": "error_type", "message": "error message"}
metadata对象会话元数据{"client_id": "web", "session_type": "chat"}

对话项状态参数表#

参数类型说明可选值
status字符串对话项状态completed, in_progress, incomplete
role字符串发送者角色user, assistant, system
type字符串对话项类型message, function_call, function_call_output

内容类型参数表#

参数类型说明可选值
type字符串内容类型text, audio, transcript
format字符串内容格式plain, markdown, html
encoding字符串编码方式utf-8, base64

响应状态参数表#

参数类型说明可选值
status字符串响应状态completed, cancelled, failed, incomplete
status_details对象状态详情{"reason": "user_cancelled"}
usage对象使用统计{"total_tokens": 50, "input_tokens": 20, "output_tokens": 30}

音频转写参数表#

参数类型说明示例值
enabled布尔值是否启用转写true
model字符串转写模型whisper-1
language字符串转写语言en, zh, auto
prompt字符串转写提示词"Transcript of a conversation"

音频流参数表#

参数类型说明可选值
chunk_size整数音频块大小(字节)1024, 2048, 4096
latency字符串延迟模式low, balanced, high
compression字符串压缩方式none, opus, mp3

WebRTC 配置参数表#

参数类型说明默认值
ice_servers数组ICE 服务器列表[{"urls": "stun:stun.l.google.com:19302"}]
audio_constraints对象音频约束{"echoCancellation": true}
connection_timeout整数连接超时(毫秒)30000
上一页
OpenAI 图像格式(Image)
下一页
OpenAI 响应格式(Responses)
Built with