# Spark-Audio-1.0 API 文档

# 一、接口说明

Spark-Audio-1.0 API 支持文本和语音两个模态的输入，输出为文本模态；支持 99 个语种 (opens new window)、202 种方言 (opens new window)，可应用于语音转写、多语言翻译、多方言识别、环境音理解、说话人分离、情感分析以及复杂音频问答等场景，使智能语音完成从"听清"到"听懂"的跃升。

技术咨询可直接提交 [工单](https://console.xfyun.cn/workorder/commit)

注意：测试或正式使用前，请去Spark-Audio-1.0产品页 (opens new window)面获取免费额度或下单购买正式套餐；同时需要去Spark-Audio-1.0控制台 (opens new window)服务页面，获取API有效密钥（AppID、APIKey、APISecret）后再调用。

# 二、接口Demo

部分开发语言Demo如下，其他开发语言请参照文档进行开发，欢迎大家到讯飞开放平台社区 (opens new window) 交流集成经验。

Spark-Audio-1.0 Demo java语言 (opens new window)

Spark-Audio-1.0 Demo python语言 (opens new window)

# 三、接口要求

内容	说明
请求协议	ws(s)（为提高安全性，强烈推荐wss）
请求地址	wss://tokens.xf-yun.com/omni/v1/realtime
接口鉴权	轻量鉴权
字符编码	UTF-8
响应格式	统一采用JSON格式
开发语言	任意，只要可以向讯飞云服务发起websocket请求的均可
音频属性	采样率16k、位长16bit、单声道
音频格式	pcm，wav
音频长度	单次 append ≤ 300s；单次会话累计 ≤ 1800s（30分钟）

# 四、接口鉴权

轻量鉴权方式，通过在ws请求头部添加用户apikey进行鉴权：

headers={
	"Authorization": "Bearer <你的 APIKEY>"
}

# 五、事件模型与会话流程

本接口基于 WebSocket 双向事件流。客户端和服务端均通过事件中的 type 字段区分事件类型

# 5.1 服务端事件类型

Type 类型	作用
session.created	会话建立连接后返回会话基本信息
session.updated	返回更新后的会话基本信息
response.text.delta	文本增量响应输出
response.text.done	文本最终完整响应输出
response.done	引擎每一轮结束的响应
input_audio_buffer.cleared	音频缓冲区已清空的确认响应
error	服务端下发错误事件

# 5.2 客户端事件类型

Type 类型	作用
session.update	更新会话基本信息
input_audio_buffer.append	上传音频到缓冲区
input_audio_buffer.clear	清空当前的音频缓冲区
input_audio_buffer.commit	手动指令启动推理

# 5.3 文本与音频发送规则

每条 input_audio_buffer.append 至少包含 audio 或 text 之一。
text 仅允许在首帧发送，且必须是完整文本内容，不允许分片；否则返回 error。
后续分片通常只上传 audio。
使用音频进行推理时，上传完成后由客户端发送 input_audio_buffer.commit 触发推理。
如果缓冲区为空时主动 commit，服务端会返回错误事件，但会话连接不一定断开。

交互时序事件：

连接建立
  客户端 -> WebSocket Connect
  服务端完成底层 Session 准备（该过程对客户端不可见）

会话状态调整
  服务端下发 -> session.created 事件，告知客户端本次会话连接的默认配置
  客户端可以选择发送 -> session.update 事件，调整本次会话连接【非必选操作】
  服务端下发 -> session.updated 事件，返回更新后的会话基本信息
  
第一轮交互
  客户端发送 -> input_audio_buffer.append 事件，上传一帧文本内容【必须首帧发送】
  客户端发送 -> input_audio_buffer.append 事件，上传一帧音频到服务音频缓冲区
  持续发送 ...
  客户端【可选】发送清空当前音频缓冲区内容请求 -> input_audio_buffer.clear 事件
  客户端发送最后一帧 -> input_audio_buffer.append 事件，上传最后一帧音频到服务音频缓冲区
  客户端主动触发推理事件 -> input_audio_buffer.commit 事件，触发对缓冲区音频的推理
  服务端推理并流式下发delta响应 -> response.text.delta 事件
  流式下发...
  服务端下发完所有delta帧，下发一条完整响应 -> response.text.done 事件，包含本轮完整的文本响应内容
  服务端下发本轮引擎推理结束事件 -> response.done 事件，本轮结束

第二轮以及后续轮次交互同第一次交互顺序进行

引擎错误交互响应
  客户端发送 -> input_audio_buffer.append 事件，上传一帧音频到服务音频缓冲区
  持续发送 ...
  客户端发送最后一帧 -> input_audio_buffer.append 事件，上传最后一帧音频到服务音频缓冲区
  客户端主动触发推理事件 -> input_audio_buffer.commit 事件，触发对缓冲区音频的推理
  引擎推理出现错误，下发错误事件 -> error 事件，会话连接断开
  
会话错误响应
  服务端主动下发错误响应 -> error 事件，参数错误不会断开会话连接；内部异常会主动断开会话连接

输入审核错误交互响应
  客户端发送 -> input_audio_buffer.append 事件，上传一帧文本内容
  服务端审核文本内容未通过审核 -> error 事件，中断会话连接，清空缓冲区内容

输出审核错误交互响应
  客户端发送 -> input_audio_buffer.append 事件，上传一帧音频到服务音频缓冲区
  持续发送 ...
  客户端发送最后一帧 -> input_audio_buffer.append 事件，上传最后一帧音频到服务音频缓冲区
  客户端主动触发推理事件 -> input_audio_buffer.commit 事件，触发对缓冲区音频的推理
  服务端下发内容时发现违禁内容 -> error 事件，中断后续响应并断开会话连接，清空缓冲区内容

# 六、事件协议

# 6.1 会话建立：`session.created`

连接建立后，服务端下发第一条事件，返回本次会话的默认配置。如需修改，客户端可发送 session.update。

{
    "event_id": " ",
    "type": "session.created",
    "session": {
        "model": "spark-audio", 
        "input_audio_format": "raw",
        "max_tokens": 8192,
        "repetition_penalty": 1.05,   
        "presence_penalty": 0.0,       
        "top_k": 50,
        "top_p": 1.0,
        "temperature": 0.8
    }
}

字段名	字段类型	含义
event_id	string	事件id
type	string	事件类型名称
session	object	会话信息
session.model	string	本次会话使用的底层模型
session.input_audio_format	string	会话指定的输入音频解析格式，当前固定为raw取值
session.max_tokens	int	会话设置后端模型的默认max tokens，当前可设置的最大值8192
session.repetition_penalty	float	控制模型生成时，连续序列中的重复度
session.presence_penalty	float	控制模型在生成内容时的重复度
session.top_k	int	本次会话默认的后端模型的top_k参数，默认 4
session.top_p	float	本次会话默认的后端模型的to p_p参数，默认 1，取值范围 (0, 1]
session.temperature	float	本次会话默认的后端模型的temperature参数，默认 0.7，取值范围 (0, 1]

# 6.2 更新会话配置：`session.update`

客户端可在会话开始阶段调整会话配置，包括系统提示词、模型参数等。会话进行中不允许发送 session.update，否则会返回错误并可能断开会话。

{
    "event_id": " ",
    "type": "session.update",
    "session": {
        "model": "spark-audio",
        "instructions": "你是实时助手，简短回答用户问题",
        "input_audio_format": "raw", 
        "max_tokens": 16384,
        "repetition_penalty": 1.05,
        "presence_penalty": 0.0,
        "top_k": 50,
        "top_p": 1.0,
        "temperature": 0.9
    }
}

字段名	是否必传	字段类型	含义
event_id	是	string	事件id
type	是	string	事件类型名称
session	是	object	会话信息
session.model	是	string	本次会话使用的底层模型
session.instructions	否	string	系统提示词，会话可以指定系统提示词引导模型处理音频
session.input_audio_format	是	string	会话指定的输入音频解析格式，当前固定为raw取值
session.max_tokens	否	int	会话设置后端模型的默认max tokens，当前可设置的最大值8192
session.repetition_penalty	否	float	控制模型生成时，连续序列中的重复度
session.presence_penalty	否	float	控制模型在生成内容时的重复度
session.top_k	否	int	后端模型的top_k参数，默认 4
session.top_p	否	float	后端模型的to p_p参数，默认 1，取值范围 (0, 1]
session.temperature	否	float	后端模型的temperature参数，默认 0.7，取值范围 (0, 1]

服务端响应

配置成功响应，返回包含本次连接的默认配置信息。字段含义同 session.created，其中 instructions 仅在客户端传入时回显。

{
    "event_id": " ",
    "type": "session.updated",
    "session": {
        "model": "spark-audio",
        "input_audio_format": "raw",
        "max_tokens": 16384,
        "repetition_penalty": 1.05,
        "presence_penalty": 0.0,
        "top_k": 50,
        "top_p": 1.0,
        "temperature": 0.8
    }
}

# 6.3 上传文本/音频分片：`input_audio_buffer.append`

客户端可持续发送多条 append，相当于用户持续说话或音频离线分片传输。

建议音频分片传输：

分片建议大小：32000 byte
分片传输间隔：40ms

{
    "event_id": " ",
    "type": "input_audio_buffer.append",
    "audio": "base64编码音频内容"，
    "text": "请翻译这段音频所说内容"
}

字段名称	是否必传	字段类型	含义
event_id	是	string	事件id
type	是	string	事件类型名称，input_audio_buffer.append
audio	与 `text` 至少传一种	string	本次上传的音频分片，建议大小32000byte，只接受 pcm / wav
text	与 `audio` 至少传一种	string	上传的文本内容，仅允许首帧发送，且必须是完整文本内容

text 不允许分片，后续音频分片通常只传 audio。

# 6.4 清空音频缓冲区：`input_audio_buffer.clear`

客户端可发送该事件清空当前尚未推理的音频缓冲区内容，清空后可继续 append 新音频再 commit。

{
  "event_id": " ",
  "type": "input_audio_buffer.clear"
}

字段名	是否必传	类型	含义
`event_id`	是	string	事件 id
`type`	是	string	事件类型名称，固定为 `input_audio_buffer.clear`

服务端响应

清空成功后服务端下发确认事件

{
    "event_id": " ",
    "type": "input_audio_buffer.cleared"
}

# 6.5 手动触发推理：`input_audio_buffer.commit`

文本/音频分片上传完成后，客户端发送 commit 触发服务端推理。

{
  "event_id": " ",
  "type": "input_audio_buffer.commit"
}

字段名	是否必传	类型	含义
`event_id`	是	string	事件 id
`type`	是	string	事件类型名称，固定为 `input_audio_buffer.commit`

如果缓冲区为空，主动触发 commit 将返回错误事件（No audio or text data to process），但会话连接不会断开。

# 6.6 文本增量响应：`response.text.delta`

服务端推理后流式下发文本增量。

{
  "event_id": " ",
  "type": "response.text.delta",
  "delta": "喂",
  "response_id": "resp_PrRSvPVpnCExdUOGHHLuP",
  "item_id": "item_L8IRm9kRXFpxoOjDqDC96",
  "output_index": 0,
  "content_index": 0
}

字段名	类型	含义
`event_id`	string	事件 id
`type`	string	事件类型名称
`delta`	string	本次流式下发的文本增量
`response_id`	string	本次引擎响应 id
`item_id`	string	消息项 id
`output_index`	int	当前固定为 0
`content_index`	int	当前固定为 0

# 6.7 文本完整响应：`response.text.done`

本轮所有增量下发完成后，服务端返回完整文本。

{
  "event_id": " ",
  "type": "response.text.done",
  "response_id": "resp_B1lIdtjF4Noqpn5NOjznj",
  "item_id": "item_B1lIdJsAJlJiFs8ztWpJt",
  "text": "喂，我现在在大东门地铁口。"
}

字段名	类型	含义
`event_id`	string	事件 id
`type`	string	事件类型名称
`response_id`	string	本次引擎响应 id
`item_id`	string	消息项 id
`text`	string	本轮引擎交互的完整文本内容

# 6.8 本轮结束：`response.done`

每一轮响应结束后返回完整总结，包含状态和 usage 等信息。

{
  "event_id": " ",
  "type": "response.done",
  "response": {
    "id": "ase000d1ff5@hu1a186955e4bf0ec862",
    "object": "realtime.response",
    "conversation_id": "cid@xxx",
    "status": "completed",
    "output_audio_format": "raw",
    "output": [
      {
        "id": "ite000e9070@dx1a186955f6fc22b100",
        "object": "realtime.item",
        "type": "message",
        "status": "completed"
      }
    ],
    "usage": {
      "total_tokens": 377,
      "input_tokens": 336,
      "output_tokens": 41,
      "input_tokens_details": {
        "text_tokens": 228,
        "audio_tokens": 108
      },
      "output_tokens_details": {
        "text_tokens": 9
      }
    }
  }
}

字段名	类型	含义
`response.id`	string	本次响应 id
`response.object`	string	响应 object 标识
`response.conversation_id`	string	本次会话连接的会话 id 标识
`response.status`	string	本轮响应状态，如成功或失败
`response.output_audio_format`	string	输出音频格式，本版本不支持输出音频
`response.output`	object	输出内容记录
`response.output.id`	string	Item id 记录
`response.output.object`	string	输出 object 信息
`response.output.type`	string	下发内容类型，目前固定为 `message`
`response.output.status`	string	响应下发状态
`response.usage`	object	底层模型用量情况
`response.usage.total_tokens`	int	总 tokens 用量
`response.usage.input_tokens`	int	输入 tokens 用量
`response.usage.output_tokens`	int	输出 tokens 用量
`response.usage.input_tokens_details`	object	输入 tokens 用量细节
`response.usage.output_tokens_details`	object	输出 tokens 用量细节

# 6.9 错误事件：`error`

服务异常、请求错误、审核拦截、后端引擎错误等统一通过 error 事件下发。

{
  "event_id": " ",
  "type": "error",
  "error": {
    "type": "response.error",
    "code": "invalid_value",
    "message": "Invalid modalities: ['audio']. Supported combinations are: ['text'] and ['audio', 'text'].",
    "param": "session.modalities"
  }
}

字段名	类型	含义
`event_id`	string	事件 id
`type`	string	事件类型，固定为 `error`
`error.type`	string	错误大类，例如 `response.error`
`error.code`	string	具体错误码，客户应以该字段判断错误类型
`error.message`	string	错误描述
`error.param`	string	出错参数位置，可能为空

建议收到 error 后记录日志，包括 event_id、error.code、error.message、error.param、response_id 等，并根据错误类型重新创建会话连接。

# 七、错误码

error.code	含义
invalid_json	客户端消息不是合法JSON，请调整发送数据保持正确可解析的json格式
invalid_request	请求参数不合法(缺音频/文本、text位置不对等)
invalid_state	当前会话状态不允许该操作
invalid_text	文本编码失败，请检查文本编码是否正确
unknown_event_type	未知的事件类型，服务只允许处理枚举范围内的客户端事件类型
auth_failed	鉴权/流控不通过，请向平台申请调用权限
blacklist	appId在黑名单，请联系平台处理
audit_blocked	输入/输出/instructions审核拦截，涉及违禁违法内容的输入输出会被拦截
engine_connect_error	连接引擎失败，请联系平台技术排查
engine_send_error	发送数据到引擎失败
engine_interrupt_error	发送中断帧失败
engine_error	引擎返回错误码，可联系平台技术同事处理
engine_disconnected	引擎连接中断，可创建新的会话连接
engine_timeout	引擎响应超时，联系平台技术同事处理
audio_limit_exceeded	音频总时长达到上限，建议重新创建新的会话连接
rounds_limit_exceeded	推理轮次达到上限，建议重新创建新的会话连接
session_timeout	会话连接时长达到上限，建议重新创建新的会话连接
audio_duration	音频总时长达到上限，建议重新创建新的会话连接
rounds	推理轮次达到上限，建议重新创建新的会话连接

# 八、常见问题

# update事件可以在会话过程中切换模型吗？

答：不可以，update事件只允许在会话开始时调整，对话开始后发送update事件会下发错误事件响应，并主动断开会话连接。

# session.updated 返回成功就代表参数生效了吗？

答：不一定。session.updated 仅代表网关接受了参数，top_p、temperature、repetition_penalty 超出取值范围时仍会回显成功，但在 commit 触发推理时由引擎下发 engine_error。请在客户端按本文给出的取值范围校验。

# 模型用量信息如何获取？

答：每轮commit触发推理后，会在response.done事件中下发usage，其中包含输入文本、输入音频、输出文本等具体tokens信息。

# update客户端事件必须发送一次吗？

答：update事件是非必选事件，会话建联后会下发本次会话的默认配置，如果不需要调整可以直接进行正常的交互事件。

# 上传的音频长度、推理轮次有限制吗？

答：有，单次会话连接中，每次音频append最大支持300s的音频；单次会话最大支持40轮推理；单次会话最多支持总共30分钟的音频处理；单次会话最大支持120分钟维持连接；空闲超时最多1分钟。超出限制后，会下发error错误事件【ErrCodeAudioLimitExceeded、ErrCodeRoundsLimitExceeded等】，清空缓冲区未发送的音频，并主动断开会话连接。

# 不发送 commit 事件，服务端会自动断句推理吗？

答：不会。本接口不做自动 VAD 断句，必须由客户端主动发送 input_audio_buffer.commit 触发推理。

# 客户端如何断开本次会话连接？

答：正常ws close即可。

# 支持的音频格式有什么要求？

答：pcm / wav音频，目前会话默认解析的input_audio_format固定为raw，后续开放更多音频格式。

# text 和 audio 必须在同一帧发送吗？

答：不必须。可以在首帧同时携带 text 与 audio，也可以先发一帧纯 text、随后持续发送纯 audio 帧，两种方式效果一致。关键约束是 text 必须在本轮第一帧、且不可分片。

在这篇文章中：