SenseVoice-small WebUI API文档RESTful接口定义与Postman测试用例1. 引言为什么需要API如果你用过SenseVoice-small的Web界面可能会觉得它很方便——上传文件、点击按钮、查看结果一切都通过鼠标点击完成。但当你需要把语音识别功能集成到自己的应用里比如开发一个自动会议纪要系统或者给手机App加上语音转文字功能时就不能总靠手动点击网页了。这时候API应用程序编程接口就派上用场了。简单来说API就是一套标准化的“指令集”让你的程序能够直接和SenseVoice-small“对话”告诉它“嘿帮我识别一下这个音频文件”然后它就会把识别结果直接返回给你的程序。这篇文章就是为你准备的API使用指南。我会用最直白的方式带你了解SenseVoice-small提供的所有API接口并且手把手教你如何用Postman一个非常流行的API测试工具来测试这些接口。无论你是开发者、测试工程师还是对技术集成感兴趣的产品经理看完这篇文章你都能掌握如何通过代码来调用这个强大的语音识别服务。2. API接口总览SenseVoice-small WebUI提供了两个核心的RESTful API端点它们覆盖了语音识别最常用的两种场景文件上传识别和实时流式识别。2.1 核心接口一览接口名称请求方法端点路径主要功能适用场景文件识别接口POST/api/audio/transcribe上传音频文件进行识别已有录音文件、会议录音、视频音频提取流式识别接口WebSocket/api/audio/transcribe_stream实时音频流识别实时语音助手、直播字幕、即时通讯语音消息2.2 接口设计特点SenseVoice-small的API设计遵循了RESTful风格这意味着资源导向每个接口对应一个具体的资源或操作比如/transcribe对应转录操作。标准HTTP方法使用POST、GET等标准方法语义清晰。状态无关每次请求都是独立的服务器不保存会话状态WebSocket除外。JSON数据格式请求和响应都使用JSON这是目前最通用的数据交换格式。这样的设计让API易于理解、易于集成也符合大多数开发者的使用习惯。3. 文件识别接口详解我们先从最常用的文件识别接口开始。这个接口适合处理你已经有的音频文件比如手机录音、会议录音、或者从视频里提取出来的音频。3.1 接口基本信息请求URLhttp://你的服务器IP:7860/api/audio/transcribe请求方法POSTContent-Typemultipart/form-data因为要上传文件3.2 请求参数说明当你调用这个接口时需要提供以下信息参数名类型是否必填说明示例值audio_fileFile是要识别的音频文件文件内容languageString否语言代码默认autozh中文、en英文taskString否识别任务类型默认transcribetranscribe转录initial_promptString否初始提示文本可提高识别准确率这是一段关于人工智能的讨论word_timestampsBoolean否是否返回词级时间戳默认falsetrueoutputString否输出格式默认jsonjson、txt、srt、vtt参数详细解释language语言如果你知道音频是什么语言最好明确指定。比如中文会议录音就传zh英文播客就传en。如果不确定或者音频里混有多种语言就用auto让模型自动检测。支持的语言代码和Web界面里的一样比如zh中文、en英文、ja日语、yue粤语等。task任务类型目前主要支持transcribe就是把语音转成文字。未来可能会支持translate翻译等任务。initial_prompt初始提示这个参数很实用。如果你知道音频的大概内容可以在这里给模型一些提示。比如音频是关于“机器学习模型训练”的你可以传这个短语模型在识别时就会更关注相关词汇。这能显著提高专业术语的识别准确率。word_timestamps词级时间戳设为true时返回结果会包含每个词的时间信息。如果你要做字幕生成这个功能特别有用可以精确控制每个词的出现时间。output输出格式json返回结构化的JSON数据包含文本、语言、情感等信息。txt只返回纯文本。srt返回SRT字幕格式包含时间轴。vtt返回WebVTT字幕格式。3.3 响应格式解析接口成功调用后会返回一个JSON对象。我们来看看这个对象里都有什么{ text: 你好这是一个语音识别测试, language: zh, language_probability: 0.98, segments: [ { id: 0, start: 0.0, end: 2.5, text: 你好这是一个, words: [ { word: 你好, start: 0.0, end: 0.8, probability: 0.95 }, { word: 这是一个, start: 0.8, end: 1.5, probability: 0.92 } ] }, { id: 1, start: 2.5, end: 4.0, text: 语音识别测试, words: [...] } ], emotion: neutral, emotion_probability: 0.85, processing_time: 1.23 }字段说明text完整的识别文本这是你最需要的内容。language检测到的语言代码。language_probability语言检测的置信度0-1之间越高越可信。segments分段信息。长音频会被自动分成若干段每段有自己的起止时间和文本。words词级详细信息当word_timestampstrue时返回。包含每个词的起止时间和识别置信度。emotion情感识别结果比如neutral中性、happy开心、sad悲伤等。emotion_probability情感识别的置信度。processing_time处理耗时单位秒。可以用来评估性能。3.4 错误处理如果调用出错接口会返回相应的HTTP状态码和错误信息状态码含义可能原因解决方法400请求错误文件格式不支持、参数格式错误检查文件格式和参数413文件太大音频文件超过限制压缩音频或分片处理422处理失败音频质量太差、无法识别提供更清晰的音频500服务器错误服务内部异常检查服务日志错误响应示例{ detail: Unsupported audio format. Please provide MP3, WAV, M4A, or OGG files. }4. 流式识别接口详解文件识别适合处理已有的录音但有些场景需要实时处理比如语音助手、直播字幕、语音聊天等。这时候就需要流式识别接口了。4.1 接口基本信息连接URLws://你的服务器IP:7860/api/audio/transcribe_stream协议WebSocket一种支持全双工通信的协议特点建立连接后可以持续发送音频数据并实时接收识别结果。4.2 为什么用WebSocket传统的HTTP请求是“一问一答”模式你发送一个请求服务器返回一个响应然后连接就关闭了。但语音识别是持续的过程你需要不断地发送音频数据同时不断地接收识别结果。WebSocket解决了这个问题长连接建立连接后一直保持不用反复建立连接。双向通信客户端和服务器可以随时互相发送消息。低延迟消息实时传输几乎没有延迟。4.3 消息格式规范WebSocket通信通过消息Message进行客户端和服务器需要遵循约定的消息格式。客户端发送的消息格式{ type: audio_data, data: base64编码的音频数据, sample_rate: 16000, language: zh, task: transcribe }字段说明type消息类型目前主要是audio_data。data音频数据的base64编码字符串。音频应该是PCM格式16位深度单声道。sample_rate采样率建议16000Hz。language语言代码可选。task任务类型可选。服务器返回的消息格式{ type: transcription, text: 识别到的文本, is_final: false, language: zh, emotion: neutral }字段说明type消息类型transcription表示识别结果。text当前识别到的文本。is_final是否是最终结果。false表示中间结果还在识别中true表示最终结果。language检测到的语言。emotion情感识别结果。4.4 完整交互流程让我们通过一个完整的例子看看流式识别是怎么工作的客户端 服务器 | | |--- WebSocket连接请求 --------------------| | | |--- 连接建立成功 -------------------------| | | |--- 发送第一段音频数据 --------------------| | | |--- 返回中间识别结果 ----------------------| | {type:transcription,text:你,is_final:false} | | | |--- 发送第二段音频数据 --------------------| | | |--- 返回更新后的识别结果 -------------------| | {type:transcription,text:你好,is_final:false} | | | |--- 发送结束标记 --------------------------| | | |--- 返回最终识别结果 ----------------------| | {type:transcription,text:你好世界,is_final:true} | | | |--- 关闭连接 -----------------------------|关键点先建立WebSocket连接分段发送音频数据比如每500毫秒发送一次服务器实时返回中间结果发送结束后服务器返回最终结果关闭连接4.5 性能优化建议流式识别对性能要求比较高这里有几个优化建议音频参数优化采样率16000Hz足够太高会增加数据量位深度16位声道单声道立体声数据量翻倍但识别效果差不多发送频率控制不要发送太频繁建议100-500毫秒发送一次每次发送的数据不要太少建议至少0.5秒的音频网络考虑确保网络稳定WebSocket对网络抖动敏感考虑添加重连机制网络中断时自动重连内存管理及时清理已发送的音频数据控制并发连接数避免服务器压力过大5. 使用Postman测试API理论讲完了现在我们来实际操作。Postman是一个非常好用的API测试工具即使你不是开发者也能轻松上手。5.1 Postman安装与设置如果你还没有Postman可以到官网下载安装。安装完成后我们先做一些基础设置新建一个Collection集合点击左上角的“New”按钮选择“Collection”命名为“SenseVoice-small API测试”设置环境变量可选但推荐点击右上角的眼睛图标选择“Environments” → “Add”添加一个变量base_url值设为你的服务器地址比如http://192.168.1.100:7860这样以后修改服务器地址时只需要改这个变量不用每个请求都改5.2 测试文件识别接口我们来创建一个测试文件识别的请求步骤1创建新请求在刚才创建的Collection上右键 → “Add Request”命名为“文件识别测试”步骤2配置请求方法选择POSTURL填写{{base_url}}/api/audio/transcribe如果你设置了环境变量这里会自动替换成实际的URL步骤3设置请求头在“Headers”标签页添加Content-Type: multipart/form-data步骤4设置请求体切换到“Body”标签页选择“form-data”添加以下参数KeyValueTypelanguagezhTexttasktranscribeTextword_timestampstrueTextoutputjsonTextaudio_file选择文件File步骤5选择测试文件点击“audio_file”行的“Select Files”选择一个测试用的音频文件MP3、WAV等格式建议准备一个清晰的、有内容的音频文件比如自己说一段话录下来步骤6发送请求并查看结果点击“Send”按钮在下方查看响应结果预期结果如果一切正常你会看到类似这样的响应{ text: 你好这是测试音频的内容, language: zh, language_probability: 0.97, segments: [...], emotion: neutral, processing_time: 1.5 }常见问题排查如果返回400错误检查文件格式是否支持参数格式是否正确如果返回500错误检查服务是否正常运行如果识别结果为空检查音频是否有声音音量是否足够5.3 测试流式识别接口流式识别接口的测试稍微复杂一些因为Postman对WebSocket的支持需要一些设置。方法一使用Postman的WebSocket功能推荐Postman从某个版本开始支持WebSocket操作步骤如下新建WebSocket请求点击“New”按钮选择“WebSocket Request”URL填写ws://你的服务器IP:7860/api/audio/transcribe_stream注意是ws://不是http://建立连接点击“Connect”按钮如果连接成功状态会显示“Connected”发送音频数据在消息输入框中输入JSON格式的消息{ type: audio_data, data: 这里需要base64编码的音频数据, sample_rate: 16000, language: zh }点击“Send”接收响应服务器返回的识别结果会显示在消息记录中方法二使用在线WebSocket测试工具如果Postman版本不支持WebSocket可以用在线工具访问https://www.piesocket.com/websocket-tester连接地址填你的WebSocket URL发送和接收消息方法三写一个简单的测试脚本如果你熟悉编程可以写一个Python脚本来测试import websocket import json import base64 import pyaudio import threading # WebSocket地址 ws_url ws://你的服务器IP:7860/api/audio/transcribe_stream def on_message(ws, message): 收到消息时的回调函数 data json.loads(message) if data[type] transcription: print(f识别结果: {data[text]} (final: {data[is_final]})) def on_error(ws, error): 出错时的回调函数 print(f错误: {error}) def on_close(ws, close_status_code, close_msg): 连接关闭时的回调函数 print(连接关闭) def on_open(ws): 连接建立时的回调函数 print(连接建立成功) # 开始录音并发送 def send_audio(): # 这里简化处理实际需要实时录音并发送 # 你可以用pyaudio录制音频然后base64编码发送 pass threading.Thread(targetsend_audio).start() # 建立连接 ws websocket.WebSocketApp( ws_url, on_openon_open, on_messageon_message, on_erroron_error, on_closeon_close ) ws.run_forever()5.4 创建完整的测试用例集一个好的测试应该覆盖各种场景。我建议你创建以下测试用例测试用例1基本功能测试目的验证接口是否能正常工作步骤上传一个清晰的普通话音频语言设为zh预期正确识别出文本返回JSON格式结果测试用例2自动语言检测测试目的测试auto语言检测功能步骤上传英文音频语言设为auto预期自动检测为英文正确识别文本测试用例3长音频测试目的测试长音频处理能力步骤上传5分钟以上的会议录音预期正确分段返回完整的识别结果测试用例4带时间戳测试目的测试词级时间戳功能步骤上传音频设置word_timestampstrue预期返回结果包含每个词的起止时间测试用例5错误处理测试目的验证错误处理机制步骤上传不支持的文件格式如.txt文件预期返回400错误和明确的错误信息测试用例6性能测试目的测试接口响应时间步骤上传不同大小的音频文件预期处理时间与文件大小基本成正比把这些测试用例保存到Postman的Collection里以后每次更新服务都可以快速跑一遍确保功能正常。6. 实际应用示例了解了API怎么用我们来看看在实际项目中如何集成。6.1 Python集成示例假设你要开发一个自动会议纪要系统需要把会议录音转成文字。下面是一个完整的Python示例import requests import json import os from datetime import datetime class SenseVoiceClient: def __init__(self, base_urlhttp://localhost:7860): self.base_url base_url self.api_url f{base_url}/api/audio/transcribe def transcribe_audio(self, audio_path, languageauto, output_formatjson): 识别音频文件 Args: audio_path: 音频文件路径 language: 语言代码 output_format: 输出格式json/txt/srt/vtt Returns: 识别结果 # 检查文件是否存在 if not os.path.exists(audio_path): raise FileNotFoundError(f音频文件不存在: {audio_path}) # 准备请求数据 files { audio_file: open(audio_path, rb) } data { language: language, output: output_format, word_timestamps: true # 获取时间戳方便做字幕 } try: # 发送请求 response requests.post(self.api_url, filesfiles, datadata) response.raise_for_status() # 如果状态码不是200抛出异常 # 根据输出格式处理响应 if output_format json: return response.json() else: return response.text except requests.exceptions.RequestException as e: print(f请求失败: {e}) if hasattr(e, response) and e.response is not None: print(f错误详情: {e.response.text}) return None finally: files[audio_file].close() def save_transcription(self, result, output_path): 保存识别结果到文件 if isinstance(result, dict): # JSON格式 with open(output_path, w, encodingutf-8) as f: json.dump(result, f, ensure_asciiFalse, indent2) else: # 文本格式 with open(output_path, w, encodingutf-8) as f: f.write(result) print(f结果已保存到: {output_path}) # 使用示例 if __name__ __main__: # 创建客户端 client SenseVoiceClient(http://192.168.1.100:7860) # 识别音频文件 audio_file meeting_recording.mp3 result client.transcribe_audio( audio_file, languagezh, output_formatjson ) if result: # 打印识别结果 print(f识别文本: {result.get(text, )}) print(f检测语言: {result.get(language, )}) print(f处理时间: {result.get(processing_time, 0)}秒) # 保存结果 timestamp datetime.now().strftime(%Y%m%d_%H%M%S) output_file ftranscription_{timestamp}.json client.save_transcription(result, output_file) # 如果需要字幕文件 srt_result client.transcribe_audio(audio_file, output_formatsrt) if srt_result: srt_file fsubtitle_{timestamp}.srt with open(srt_file, w, encodingutf-8) as f: f.write(srt_result) print(f字幕文件已保存: {srt_file})6.2 流式识别集成示例对于实时语音识别场景比如语音助手我们需要使用流式接口import websocket import json import base64 import pyaudio import threading import queue import time class StreamTranscriber: def __init__(self, server_urlws://localhost:7860): self.server_url server_url self.ws None self.audio_queue queue.Queue() self.is_recording False self.transcription_callback None def set_callback(self, callback): 设置识别结果回调函数 self.transcription_callback callback def on_message(self, ws, message): 收到识别结果 try: data json.loads(message) if data[type] transcription and self.transcription_callback: self.transcription_callback(data) except json.JSONDecodeError as e: print(f解析消息失败: {e}) def on_error(self, ws, error): print(fWebSocket错误: {error}) def on_close(self, ws, close_status_code, close_msg): print(f连接关闭: {close_msg}) self.is_recording False def on_open(self, ws): print(连接建立成功) # 开始发送音频数据 threading.Thread(targetself.send_audio_data).start() def start_recording(self): 开始录音并连接服务器 # 初始化音频录制 self.audio pyaudio.PyAudio() self.stream self.audio.open( formatpyaudio.paInt16, channels1, rate16000, inputTrue, frames_per_buffer1024 ) # 连接WebSocket self.ws websocket.WebSocketApp( self.server_url, on_openself.on_open, on_messageself.on_message, on_errorself.on_error, on_closeself.on_close ) self.is_recording True # 开始录音线程 threading.Thread(targetself.record_audio).start() # 运行WebSocket self.ws.run_forever() def record_audio(self): 录制音频并放入队列 print(开始录音...) while self.is_recording: data self.stream.read(1024, exception_on_overflowFalse) self.audio_queue.put(data) time.sleep(0.01) # 避免队列堆积太快 def send_audio_data(self): 从队列获取音频数据并发送 print(开始发送音频数据...) while self.is_recording: try: # 收集0.5秒的音频数据 chunks [] for _ in range(8): # 1024 samples * 8 约0.5秒 if not self.audio_queue.empty(): chunks.append(self.audio_queue.get()) else: time.sleep(0.01) if chunks: # 合并并编码音频数据 audio_data b.join(chunks) audio_base64 base64.b64encode(audio_data).decode(utf-8) # 发送到服务器 message { type: audio_data, data: audio_base64, sample_rate: 16000, language: zh } self.ws.send(json.dumps(message)) except Exception as e: print(f发送音频数据失败: {e}) def stop(self): 停止录音和识别 self.is_recording False if self.stream: self.stream.stop_stream() self.stream.close() if self.audio: self.audio.terminate() if self.ws: self.ws.close() # 使用示例 def handle_transcription(data): 处理识别结果的回调函数 text data.get(text, ) is_final data.get(is_final, False) if is_final: print(f[最终结果] {text}) else: print(f[中间结果] {text}) if __name__ __main__: transcriber StreamTranscriber(ws://192.168.1.100:7860/api/audio/transcribe_stream) transcriber.set_callback(handle_transcription) try: # 开始录音和识别 transcriber.start_recording() except KeyboardInterrupt: print(\n停止识别...) transcriber.stop()6.3 错误处理与重试机制在实际生产环境中网络可能不稳定服务可能暂时不可用。我们需要添加健壮的错误处理和重试机制import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry import time class RobustSenseVoiceClient: def __init__(self, base_url, max_retries3): self.base_url base_url self.api_url f{base_url}/api/audio/transcribe # 配置重试策略 retry_strategy Retry( totalmax_retries, backoff_factor1, # 重试间隔1, 2, 4秒 status_forcelist[429, 500, 502, 503, 504], # 需要重试的状态码 allowed_methods[POST] # 只对POST请求重试 ) # 创建带重试的Session self.session requests.Session() adapter HTTPAdapter(max_retriesretry_strategy) self.session.mount(http://, adapter) self.session.mount(https://, adapter) def transcribe_with_retry(self, audio_path, max_retries3): 带重试的语音识别 for attempt in range(max_retries): try: print(f第{attempt 1}次尝试...) with open(audio_path, rb) as audio_file: files {audio_file: audio_file} data {language: auto} response self.session.post( self.api_url, filesfiles, datadata, timeout30 # 设置超时时间 ) response.raise_for_status() return response.json() except requests.exceptions.Timeout: print(f请求超时{3 - attempt - 1}次重试剩余) if attempt max_retries - 1: time.sleep(2 ** attempt) # 指数退避 continue except requests.exceptions.RequestException as e: print(f请求失败: {e}) if attempt max_retries - 1: time.sleep(2 ** attempt) continue print(所有重试均失败) return None def check_service_health(self): 检查服务健康状态 try: # 尝试一个简单的请求 response requests.get(f{self.base_url}/, timeout5) return response.status_code 200 except: return False # 使用示例 client RobustSenseVoiceClient(http://192.168.1.100:7860) # 检查服务状态 if client.check_service_health(): print(服务正常) result client.transcribe_with_retry(test_audio.mp3) if result: print(f识别成功: {result[text][:50]}...) else: print(服务不可用请检查服务状态)7. 总结通过这篇文章我们详细了解了SenseVoice-small WebUI的API接口。让我们回顾一下关键点7.1 核心要点回顾两个核心接口文件识别接口POST/api/audio/transcribe适合处理已有的音频文件流式识别接口WebSocket/api/audio/transcribe_stream适合实时语音处理丰富的功能特性支持50种语言识别自动语言检测情感识别词级时间戳多种输出格式JSON、TXT、SRT、VTT易于集成标准的RESTful API设计清晰的请求/响应格式完善的错误处理机制实用工具支持使用Postman可以方便地测试API提供了完整的Python集成示例包含错误处理和重试机制7.2 最佳实践建议根据我的经验这里有一些建议可以帮助你更好地使用这些API选择合适的接口如果处理已有文件用文件识别接口如果需要实时处理用流式识别接口两者不要混用每个接口都有最适合的场景参数优化明确指定语言能提高识别准确率使用initial_prompt提供上下文信息根据需求选择是否开启词级时间戳性能考虑音频采样率16000Hz足够太高反而增加处理负担控制并发请求数避免服务器压力过大流式识别时合理控制发送频率错误处理一定要添加重试机制监控服务健康状态记录详细的错误日志安全考虑如果服务暴露在公网考虑添加认证机制限制文件大小和请求频率定期更新服务版本7.3 下一步学习建议如果你已经掌握了这些API的基本使用可以进一步探索性能调优尝试不同的音频参数找到最适合你场景的配置批量处理开发批量处理脚本一次性处理大量音频文件集成到现有系统将语音识别功能集成到你的业务系统中监控和告警添加服务监控及时发现和处理问题自定义开发基于开源代码进行二次开发添加定制功能API只是工具真正的价值在于如何用它解决实际问题。无论是开发语音助手、自动字幕系统还是智能客服质检SenseVoice-small都能提供强大的语音识别能力。关键是理解你的业务需求选择合适的接口和参数然后不断测试和优化。希望这份文档能帮助你快速上手SenseVoice-small的API。如果在使用过程中遇到问题记得查看服务日志大多数问题都能在那里找到答案。祝你开发顺利获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。