1. 模型说明

能力	Seeduplex 全双工实时语音
端到端实时语音对话（低时延、全双工）	✅
流式 ASR / 流式文本回复 / 流式音频合成	✅
Function Calling	✅
上下文注入与管理	✅
专有能力（extension：ASR/TTS/Dialog 透传，如联网、唱歌、热词等）	联网、热词等功能暂未开启

2. 功能接口详情

2.1 全双工实时语音 WebSocket

2.1.1 请求 url

wss://genaiapi-m2.cloudsway.net/ws/api/v1/ai/{YOUR_ENDPOINT}/doubao/s2s

{YOUR_DOMAIN}：平台分配的接入域名。
{YOUR_ENDPOINT}：平台分配的接入端点标识（路径段）。

2.1.2 握手请求头参数

参数名	字段类型	是否必填	默认值	描述
Authorization	string	二选一	-	API Key 凭证（与平台约定的鉴权头）

2.1.3 消息帧与通用字段

每条 WebSocket Text Message 承载一个完整事件 JSON。
收发双方按顶层 type 字段分发处理。
下列字段在多个事件中复用：

参数名	字段类型	是否必填	描述
type	string	是	事件类型，见 §2.2、§2.3
event_id	string	否	客户端发起请求时，可生成并传入自定义`event_id`，该字段为可选，建议传入，用于后续事件匹配与追踪

2.1.4 会话生命周期（建议时序）

客户端                          平台
  │── WebSocket 建连（鉴权） ──▶│
  │── session.create ──────────▶│
  │◀── session.created ─────────│   （含 session.id，可接续历史）
  │── input_audio_buffer.append ▶│   （循环：音频 / 其它上行事件）
  │◀── 转写 / 文本 / 音频 / 用量 ──│
  │── session.close ───────────▶│
  │◀── session.closed ──────────│
  │── 关闭 WebSocket ──────────▶│

要点：

建议 session.create 后等待 session.created 再开始推流。
接续历史：在 session.update 的 session.id 中回传上次 session.created 返回的 session.id（即 dialog id）；服务端默认保留最近 20 轮问答。
优雅关闭：先发送 session.close 并收到 session.closed 后再关闭 WebSocket；直接断开可能触发 ContextCanceled（错误码 55000001）。
Keep alive：，input_audio_mute.commit仅保证与模型侧保持会话，而不保证与平台保持连接，建议每隔10秒发送一个静音包来保持连接与平台的连接，超过90秒无静音包，平台将释放连接，超过 10 分钟无交互，模型侧可能释放连接（错误码 45000003）。
实例维护等场景下，客户端可能先收到平台下发的 session.closing（见 §2.3.21），随后连接关闭。建议在收到该事件后，重新连接，避免服务端中断

2.1.5 请求示例（建连后发送 session.create）

{
  "type": "session.create",
  "event_id": "evt_create_001",
  "session": {
    "instructions": "你是友好的语音助手。",
    "audio": {
      "input": { "format": { "type": "pcm", "rate": 16000 } },
      "output": {
        "format": { "type": "ogg_opus", "rate": 24000 },
        "voice": "YOUR_VOICE_ID",
        "speed": 0,
        "loudness": 0
      }
    },
    "extension": {
      "asr": {},
      "tts": {},
      "dialog": {}
    }
  }
}

2.1.6 响应示例（session.created）

响应头中会包含X-Tt-Logid字段

{
  "type": "session.created",
  "session": {
    "id": "dlg_xxxxxxxx"
  }
}

2.2 上行事件（客户端 → 服务端）

以下各节「请求参数」指单帧 JSON 根对象字段（除已列通用字段外）。

2.2.1 session.create / session.update

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	指定请求事件类型。创建会话时，字段固定为`session.create`；更新会话时，字段固定为`session.update`
session	object	是	-	会话配置
session.id	string	否	-	对应原 dialog id，接续历史对话时传入
session.instructions	string	否	-	系统提示词（System message），用于引导模型的回复内容与音频风格，与模型内部 SP 及上下文合计长度上限为 12K tokens
session.audio	object	是	-	音频输入输出规格
session.audio.input	object	是	-	输入音频配置
session.audio.input.format	object	否	-	指定上传音频的规格
session.audio.input.format.type	string	否	-	指定输入音频格式，支持`pcm`和`speech_opus`
session.audio.input.format.rate	int	否	-	指定输入音频采样率，仅支持`16000`，单位为Hz
session.audio.output	object	是	-	输出音频配置
session.audio.output.format	object	否	-	指定输出音频规格
session.audio.output.format.type	string	否	-	指定输出音频格式，支持`pcm`和`ogg_opus`
session.audio.output.format.rate	int	否	-	指定输出音频采样率，仅支持`24000`，单位为Hz
session.audio.output.voice	string	是	-	指定音色ID，目前支持音色详见：音色列表，同时也支持复刻音色
session.audio.output.speed	number	否	0	指定语速，默认值为`0`，取值范围：[`-50`,`100`]，取值越大，语速越快。`-50`代表0.5倍速，`100`代表2.0倍速，默认不调整语速
session.audio.output.loudness	number	否	0	指定音量，默认值为`0`，取值范围：[`-50`,`100`]，取值越大，音量越大。`-50`代表0.5倍音量，`100`代表2.0倍音量，默认不调整音量
session.tools	array	否	-	Function Calling 工具定义，使用标准 JSON Schema 结构
session.extension	object	否	-	配置模型透传参数
session.extension.asr	object	否	-	配置ASR参数
session.extension.asr.extra	object	否	-	配置ASR附加参数
session.extension.asr.extra.enable_asr_twopass	bool	否	false	启用非流式模型识别能力，默认为`false`
session.extension.asr.extra.boosting_table_id	string	否	-	暂未支持热词词表id
session.extension.asr.extra.boosting_table_name	string	否	-	暂未支持热词词表名称
session.extension.asr.extra.regex_correct_table_id	string	否	-	暂未支持
session.extension.asr.extra.regex_correct_table_name	string	否	-	暂未支持
session.extension.asr.extra.context	string	否	-	暂未支持
session.extension.dialog	object	否	-	配置Dialog参数
session.extension.dialog.location	string	否	-	位置信息配置，支持以下字段：`longitude`（经度）、`latitude`（纬度）、`city`（城市）、`country`（国家）、`province`（省份）、`district`（区县）、`town`（乡镇 / 街道）、`country_code`（国家代码）、`address`（详细地址）
session.extension.dialog.dialog_context	array	否	-	初始化上下文，需按照`user`/`assistant`成对传入QA
session.extension.dialog.dialog_context[].role	string	否	-	指定对话角色：`user`/`assistant`
session.extension.dialog.dialog_context[].text	string	否	-	传入对话文本
session.extension.dialog.dialog_context[].timestamp	int	否	-	传入对话时间戳
session.extension.dialog.extra	string	否	-	配置Dialog附加参数
session.extension.dialog.extra.strict_audit	bool	否	true	开启严格审核，默认为`true`
session.extension.dialog.extra.audit_response	string	否	-	指定用户query命中安全审核时的自定义回复话术
session.extension.dialog.extra.enable_volc_websearch	bool	否	false	暂未支持开启内置联网功能，默认为`false`，开通服务请参考控制台融合信息搜索API
session.extension.dialog.extra.volc_websearch_type	string	否	-	暂未支持用于指定搜索服务类型，支持 `web_custom_api`、`web_global_api`
session.extension.dialog.extra.enable_music	bool	否	false	开启唱歌能力，默认为`false`，开启后，系统将从曲库检索唱歌数据并传入模型，以提升模型唱歌表现
session.extension.dialog.extra.enable_loudness_norm	bool	否	false	开启输出音频响度均衡能力，默认为`false`
session.extension.dialog.extra.enable_user_query_exit	bool	否	false	开启退出意图识别能力，默认为`false`，开启后，服务端将在`response.output_audio.done`事件中携带退出意图信号，供客户端执行退出操作
session.extension.tts	object	否	-	配置TTS参数
session.extension.tts.extra	object	否	-	配置TTS附加参数
session.extension.tts.extra.max_length_to_filter_parenthesis	int	否	0	指定过滤括号内文本的长度，单位为字符，默认为0（即不过滤），推荐取值范围0\~100
session.extension.tts.extra.explicit_dialect	string	否	-	指定方言参数，支持的方言：`dongbei`、`sichuan`、`shaanxi`、`yue`、`beijing`、`henan`、`tianjin`、`shanghai`
session.extension.tts.extra.aigc_metadata	string	否	-	配置AIGC 内容溯源与版权元信息

session.update 对 tools 为全量覆盖（非增量），可动态增删工具。

2.2.2 session.close

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	请求事件类型。结束会话时，字段固定为`session.close`

2.2.3 input_audio_buffer.append

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	指定请求事件类型。发送请求时，字段固定为`input_audio_buffer.append`
audio	string	是	-	传入音频数据，音频数据经 Base64 编码后填入`audio`字段，完整事件以 JSON 文本帧形式发送

2.2.4 input_audio_buffer.commit

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	指定请求事件类型。发送请求时，字段固定为`input_audio_buffer.commit` 。确认音频 query 发送完毕后，可发送该事件强制模型判停

2.2.5 input_audio_mute.commit / input_audio_unmute.commit

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	关闭麦克风后发送 `input_audio_mute.commit`；恢复麦克风时发送 `input_audio_unmute.commit`（即 `type` 指定为对应事件名）

2.2.6 speech_text_buffer.commit

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	指定请求事件类型。用于打招呼，字段固定为`speech_text_buffer.commit`
text	string	是	-	输入待合成的“打招呼”文本

2.2.7 speech_text_buffer.replacement.append / speech_text_buffer.replacement.commit

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	指定请求事件类型。用于流式打招呼，或不需要模型闲聊结果、希望直接指定文本合成音频的场景。`speech_text_buffer.replacement.append`：流式上传待合成文本；`speech_text_buffer.replacement.commit`：结束包（文本上传完成）
text	string	是	-	输入待合成的文本

2.2.8 conversation.item.create（上下文 / Function Calling 结果）

上下文初始化

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	指定请求事件类型。发送请求时，字段固定为`conversation.item.create`
items	array	是	-	新增上下文对话信息，可用于初始化历史上下文。每次最多提交 20 轮（40 条）完整 QA
items[].id	string	否	-	指定自定义的上下文对话id
items[].type	string	是	-	指定上下文类型，固定为`message`
items[].role	string	是	-	指定对话角色，可选值`user`、`assistant`
items[].content	array	是	-	指定对话内容

Function Calling 结果回传（在 response.function_call_arguments.done 之后）

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	请求事件类型。发送请求时，字段固定为`conversation.item.create`。该事件用于在下行事件`response.function_call_arguments.done` 返回后，上报工具执行结果，供模型基于工具数据继续生成回复
items	array	是	-	指定函数回传信息
items[].call_id	string	是	-	函数调用的唯一标识，用于回传函数调用结果，须与下行事件`response.function_call_arguments.done`下发的`call_id` 保持一致
items[].role	string	是	-	指定条目角色信息，固定值为`tool`，标识该item为函数调用结果
items[].content	array	是	-	传入函数调用的结果信息
items[].content[].type	string	是	-	内容类型，固定值为 `input_text`
items[].content[].text	string	是	-	传入函数调用的执行结果

2.2.9 conversation.item.update

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	请求事件类型。发送请求时，字段固定为`conversation.item.update`
items	array	是	-	指定待更新的上下文信息
items[].id	string	是	-	指定待更新的对话id
items[].content	array	是	-	传入待更新的对话内容

2.2.10 conversation.item.retrieve

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	请求事件类型。发送请求时，字段固定为`conversation.item.retrieve`
items	array	否	-	指定待查询的上下文信息
items[].id	string	否	-	传入待查询的对话id，返回该轮次上下文信息，不传则返回最近20轮完整上下文信息

2.2.11 conversation.item.delete

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	请求事件类型。发送请求时，字段固定为`conversation.item.delete`
items	array	是	-	指定待删除的上下文信息
items[].id	string	是	-	指定待删除的对话id

上下文删除以对话轮为单位进行，传入 user 侧 id 时将同时删除成对的 assistant 回复，反之亦然。

2.2.12 response.cancel

参数名	字段类型	是否必填	默认值	描述
type	string	是	-	请求事件类型。发送请求时，字段固定为`response.cancel`。用于取消进行中的响应，即客户端主动打断服务端播报，便于进行下一次识别。

2.3 下行事件（服务端 → 客户端）

握手成功后，响应亦为 WebSocket Text Message JSON。除下列字段外，多数事件可携带 event_id（与上行对应或服务端生成）。

2.3.1 session.created

参数名	字段类型	描述
type	string	固定为 `session.created`
session	object	会话信息
session.id	string	该事件表示会话已成功启动，返回的`session.id`（对应原版本`dialog.id`），可用于接续历史对话内容。

2.3.2 session.updated

参数名	字段类型	描述
type	string	固定为 `session.updated`
session	object	该事件为 `session.update` 请求对应的确认响应（ack），表示会话配置已成功更新

2.3.3 session.closed

参数名	字段类型	描述
type	string	固定为 `session.closed`
—	—	该事件为会话已结束（`session.close` 的应答）

2.3.4 input_audio_buffer.committed

参数名	字段类型	描述
type	string	固定为 `input_audio_buffer.committed`
—	—	该事件用于通知客户端输入音频缓冲区已成功提交，标志着一次用户音频输入的结束

2.3.5 conversation.item.input_audio_transcription.started

参数名	字段类型	描述
type	string	固定为 `conversation.item.input_audio_transcription.started`
—	—	模型识别出音频流中的首字时返回

2.3.6 conversation.item.input_audio_transcription.delta

参数名	字段类型	描述
type	string	固定为 `conversation.item.input_audio_transcription.delta`
delta	string	模型实时识别出的用户说话文本内容（流式增量）

2.3.7 conversation.item.input_audio_transcription.completed

参数名	字段类型	描述
type	string	固定为 `conversation.item.input_audio_transcription.completed`
—	—	模型判定用户说话结束时返回

2.3.8 conversation.item.input_audio_transcription.failed

参数名	字段类型	描述
type	string	固定为 `conversation.item.input_audio_transcription.failed`
—	—	ASR 识别失败

2.3.9 response.output_text.delta

参数名	字段类型	描述
type	string	固定为 `response.output_text.delta`
delta	string	模型回复的文本内容（流式增量）

2.3.10 response.output_text.done

参数名	字段类型	描述
type	string	固定为 `response.output_text.done`
—	—	模型回复文本生成结束

2.3.11 response.output_audio.started

参数名	字段类型	描述
type	string	固定为 `response.output_audio.started`
—	—	一轮音频合成开始

2.3.12 response.output_audio.delta

参数名	字段类型	描述
type	string	固定为 `response.output_audio.delta`
delta	string	返回的流式音频数据块，Base64 编码

2.3.13 response.output_audio.done

参数名	字段类型	描述
type	string	固定为 `response.output_audio.done`
status_code	string	模型一轮音频合成结束。其中 `status_code="20000002"` 表示模型识别到用户的退出意图

2.3.14 conversation.item.added

参数名	字段类型	描述
type	string	固定为 `conversation.item.added`
items	array	新增上下文请求的确认（ack），返回创建成功的上下文数组

2.3.15 conversation.item.retrieved

参数名	字段类型	描述
type	string	固定为 `conversation.item.retrieved`
items	array	查询上下文请求的确认（ack），返回查询到的上下文内容

2.3.16 conversation.item.deleted

参数名	字段类型	描述
type	string	固定为 `conversation.item.deleted`
items	array	删除上下文请求的确认（ack），返回被删除的上下文内容
status_code	string	若没有可删除的上下文，可能返回如 `40000010`
message	string	错误说明，如 `empty conversation deleted messages`

2.3.17 response.function_call_arguments.done

参数名	字段类型	描述
type	string	固定为 `response.function_call_arguments.done`
items	array	FC函数调用参数生成完成。下行 `items` 每个函数调用项均带有唯一的`call_id`、函数名`name` 与生成好的参数 `arguments`（JSON 字符串）。客户端执行本地函数后，须通过 `conversation.item.create`（role=tool）回传结果，并在回传项中携带相同的 call_id

2.3.18 response.done

参数名	字段类型	描述
type	string	固定为 `response.done`
response	object	本轮响应信封
response.usage	object	一轮交互结束，返回本次用量统计
response.usage.total_tokens	int	本轮总 token 数
response.usage.input_tokens	int	输入 token 数
response.usage.output_tokens	int	输出 token 数
response.usage.input_token_details	object	输入 token 明细
response.usage.input_token_details.text_tokens	int	输入文本 token
response.usage.input_token_details.audio_tokens	int	输入音频 token
response.usage.input_token_details.image_tokens	int	输入图片 token
response.usage.input_token_details.cached_tokens	int	缓存命中 token 总数
response.usage.input_token_details.cached_tokens_details	object	缓存命中明细
response.usage.input_token_details.cached_tokens_details.text_tokens	int	缓存命中文本 token
response.usage.input_token_details.cached_tokens_details.audio_tokens	int	缓存命中音频 token
response.usage.input_token_details.cached_tokens_details.image_tokens	int	缓存命中图片 token
response.usage.output_token_details	object	输出 token 明细
response.usage.output_token_details.text_tokens	int	输出文本 token
response.usage.output_token_details.audio_tokens	int	输出音频 token

响应示例

{
  "type": "response.done",
  "event_id": "event_119",
  "response": {
    "usage": {
      "total_tokens": 796,
      "input_tokens": 246,
      "output_tokens": 550,
      "input_token_details": {
        "text_tokens": 0,
        "audio_tokens": 246,
        "image_tokens": 0,
        "cached_tokens": 0,
        "cached_tokens_details": {
          "text_tokens": 0,
          "audio_tokens": 0,
          "image_tokens": 0
        }
      },
      "output_token_details": {
        "text_tokens": 185,
        "audio_tokens": 365
      }
    }
  }
}

2.3.19 response.canceled

参数名	字段类型	描述
type	string	固定为 `response.canceled`
—	—	客户端打断请求`response.cancel`的确认（ack）

2.3.20 error

参数名	字段类型	描述
type	string	固定为 `error`
status_code	string	错误码（也可能位于嵌套 `error` 对象内，以实际报文为准）
message	string	错误说明

错误事件，错误表详见接入必读错误码说明。客户端应对所有下行 error 事件做统一捕获与日志记录。

2.3.21 session.closing（平台提示）

参数名	字段类型	描述
type	string	固定为 `session.closing`

在实例维护或平台侧即将关闭连接时，客户端可能先收到该事件，随后连接关闭。建议在收到该事件后，重新连接，避免服务端中断

2.4 音频格式与推流

输入音频

格式：PCM / Opus（Opus 由服务端自动转为 PCM）、单声道、16000Hz、int16、小端序；
音频分片建议以20 ms 为单位（16k /int16 格式下每包 640 字节），并严格按照实时音频流的节奏发送，发送速率偏离实际节奏（过快或过慢）都将触发服务端错误；
音频字节经 Base64 编码后放入 audio 字段。

输出音频

默认 OGG-Opus；可在 session 的 audio.output.format 或 extension.tts.audio_config 中配置为 PCM（24000Hz，单声道，16bit 小端序）；
流式块在 response.output_audio.delta 的 delta 字段（Base64）。

2.5 常见错误码

错误码	关键字	描述与处理建议
42000020	volc_websearch_bot_id is required 等	web_agent 联网模式缺 `bot_id` / 缺 `api_key`（核对配置）
45000003	Abnormal silence audio	超过 10 分钟无交互，服务端释放连接
50000000	AudioQueryError	模型推理出错
—	found unknown escape character	`speaking_style` / `system_role` 含非法字符，建议检查 prompt
55000001	ServerError	模型推理出错
55000001	ContextCanceled	未正常发送 `session.close` 即断开；务必收到回复再断连
55000001	ClientError:InvalidSpeaker	音色名不合法
55000001	ExceededConcurrentDurationLimit	并发时长超限
50700000	stream recv timeout	模型推理超时
52000022	AudioChatError	模型推理出错
52000035	S2SQueryConnectError	模型推理出错

2.6 注意事项

优雅关闭：先 session.close，收到 session.closed 后再关 WebSocket。
模型侧的静音保活：关闭麦克风后发送 input_audio_mute.commit，恢复时发送 input_audio_unmute.commit。
Keep alive：input_audio_mute.commit仅保证与模型侧保持会话，而不保证与平台保持连接，建议每隔10秒发送一个静音包来保持与平台的连接，超过90秒无静音包，平台将释放连接，超过 10 分钟无交互，模型侧可能释放连接（错误码 45000003）。
event_id：建议所有上行事件携带 event_id。
上下文：conversation.item.create 初始化时 user/assistant 成对提交；时间戳要么全带（递增且不超过当前时间）要么全不带。
Function Calling：session.update 的 tools 全量覆盖；按 call_id 配对回传 tool 结果；并行调用分别执行后聚合一次性回传。
extension：专有能力（ASR/TTS/Dialog）统一放在 session.extension，随 session.create / session.update 下发。
实例维护等场景下，客户端可能先收到平台下发的 session.closing（见 §2.3.21），随后连接关闭。建议在收到该事件后，重新连接，避免服务端中断