模型下发接口说明（V2）--豆包语音-火山引擎

文档中心

导航

模型下发接口说明（V2）

最近更新时间：2025.07.03 13:42:43首次发布时间：2021.12.20 14:44:12

SDK的离线功能需要离线模型资源，我们提供了相关接口完成动态下载、更新模型数据以及检测模型是否可用。

状态码

模型下发相关接口统一的状态码定义。

枚举名	枚举值	含义
kSERSuccess	0	成功
kSERDownloadFailed	-1	模型下载失败
kSERUnzipFailed	-2	模型解压失败
kSERCreateFileFailed	-3	模型文件创建失败
kSERFetchModelInfoFailed	-4	查询模型信息失败

初始化模型下发

模型下发能力依赖语音合成 SDK 的网络功能, 在初始化模型下发之前必须先完成环境依赖的相关配置。
配置模型下发各项参数，并调用初始化接口。该接口需要在其他部分接口开始前完成调用。

参数说明

参数名	参数类型	是否必须	默认值	含义
DeviceId	string	是	""	设备 ID，用于判断特定用户，以便查找相关日志定位问题。
AppId	string	是	""	应用 Id，用于确定当前业务方。
AppVersion	string	是	""	App 版本号。
RootPath	string	是	""	模型下发根路径，包括模型缓存、配置文件、最终模型等都会放在这个目录下。这个目录下最好不要存放其他文件，因为在模型升级时，有时会将这个目录清空。
OnlineModelEnable	bool	是	true	是否使用线上模型，非联调场景不要使用线下模型。

示例代码

#import "SpeechResourceManager.h"

SpeechResourceManager *speechResourceManager = [SpeechResourceManager shareInstance];
[speechResourceManager setAppId:@"{APP ID}"];
[speechResourceManager setAppVersion:@"{APP VERSION}"];
[speechResourceManager setDeviceId:@"{DEVICE ID}"];
[speechResourceManager setRootPath:@"{ROOT PATH}"];
[speechResourceManager setOnlineModelEnable:YES];
[speechResourceManager setup];

检测模型是否存在

判断模型是否存在，不要在初始化执行完成后立刻进行检查。建议将初始化放在 App 启动时，而在需要时再检测模型是否存在。

#import "SpeechResourceManager.h"

SpeechResourceManager *speechResourceManager = [SpeechResourceManager shareInstance];
BOOL modelExist = [speechResourceManager checkModelExist:SE_TTS_MODEL];

检测模型是否需要更新

该接口为异步接口，调用时需提供回调。

示例代码

#import "SpeechResourceManager.h"

SpeechResourceManager *speechResourceManager = [SpeechResourceManager shareInstance];
[speechResourceManager checkModelVersion:SE_TTS_MODEL completion:^(SEResourceStatus status, BOOL needUpdate, NSData *data) {
    if (status == kSERSuccess) {
        if (needUpdate) {
            NSLog(@"Model need update");
        } else {
            NSLog(@"Model doesn't need update");
        }
    } else {
        NSLog(@"Model check failed: %@", [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]);
    }
}];

回调参数说明

回调参数	类型	含义
status	SEResourceStatus	参考状态码部分说明
needUpdate	BOOL	是否需要更新模型
data	NSData *	额外信息，状态码为成功时值为模型路径，状态码为失败时值为错误信息。

下载/更新至最新模型

该接口为异步接口，调用时需提供回调。

示例代码

#import "SpeechResourceManager.h"

SpeechResourceManager *speechResourceManager = [SpeechResourceManager shareInstance];
[speechResourceManager fetchModelByName:SE_TTS_MODEL completion:^(SEResourceStatus status, NSData* data) {
    if (status == kSERSuccess) {
        NSLog(@"Model download succeed");
    } else {
        NSLog(@"Mode download failed");
    }
}];

回调参数说明

回调参数	类型	含义
status	SEResourceStatus	参考状态码部分说明
data	NSData *	额外信息，状态码为成功时值为模型路径，状态码为失败时值为错误信息。

获取模型路径

获取模型路径。该接口只是返回模型路径，并不保证该路径存在或模型是否可用。但如果成功下载了模型，最终模型文件必定会在此路径下。配置离线资源路径时，可以使用该接口的返回值。

#import "SpeechResourceManager.h"

SpeechResourceManager *speechResourceManager = [SpeechResourceManager shareInstance];
NSString *modelPath = [speechResourceManager getModelPath:SE_TTS_MODEL];