Avatar 虚拟形象
  • iOS
  • Android : Java
  • 产品简介
  • 下载
  • 下载体验 App
  • 快速开始
    • 跑通示例源码
    • 集成 SDK
    • 在线鉴权
    • 创建虚拟形象
    • ZegoCharacterHelper 使用说明
  • 基本功能
  • 进阶功能
  • 最佳实践
  • 常见错误码
  • 服务端 API
  • 客户端 API
  • 常见问题

创建虚拟形象

更新时间:2023-03-09 19:50

前提条件

在实现基本的 Avatar 功能之前,请确保:

  • 已在项目中集成了 Avatar SDK,详情请参考 集成 SDK
  • 已开启摄像头权限。

使用步骤

本节介绍如何使用 ZegoAvatar SDK 实现基本的图像处理功能,API 调用时序如下图:

1 申请鉴权

ZEGO Avatar 目前使用 在线鉴权 的方式获取 License 授权文件。

1.1 开通 ZegoAvatar 权限

  1. 请先在 ZEGO 控制台 创建项目,并申请有效的 AppID 和 AppSign,详情请参考 控制台 - 项目管理 中的“项目信息”。

  2. 请联系 ZEGO 商务人员,提供自己项目的包名,开通相关权限。

1.2 获取参考代码

请将从 下载 获取到的示例源码中的 im.zego.zegoavatarexample.licensehelper 中的代码,拷贝到自己的项目下。

  1. 导入依赖库文件。

    // 导入以下依赖库文件
    implementation "com.google.code.gson:gson:2.8.8"
    implementation 'com.squareup.okhttp3:okhttp:4.9.0'
  2. 修改 ZegoAvatarConfig.java 文件,请使用已获取的 AppID 和 AppSign 正确填写,否则示例源码无法正常运行。

    public class ZegoAvatarConfig {
        // 鉴权服务器的地址
        public final static String BACKEND_API_URL = "https://aieffects-api.zego.im?Action=DescribeAvatarLicense";
        // 获取到的 AppID, APPID 跟 ApplicationId 有绑定关系, 请修改 app/build.gradle 下的 ApplicationId 为申请 AppID 时提供的包名
        public final static long APP_ID = YOUR_APP_ID;
        // 获取到的 AppSign
        public final static String APP_SIGN = YOUR_APP_SIGN;
    }
  3. 修改 “app/build.gradle” 文件,将 “applicationId” 设置为申请权限时所提供的包名。

1.3 获取 License

通过 ZegoLicenseHelper 中的 getLicense 接口,发起网络请求,获取鉴权 License 字符串。

此处的在线鉴权,返回的只是鉴权数据。初始化 SDK 时,仍然需要校验该鉴权数据,ZEGO 建议开发者定时更新、拉取鉴权数据,防止鉴权文件过期,导致 SDK 校验不通过的问题。

public static String zegoLicense;
ZegoLicenseHelper.getLicense(this, (code, message, response) -> {
    //获取 License 成功
    if (code == 0) {
        // 使用全局变量保存 License,以便下一步 init 时使用
       zegoLicense = response.getLicense();
    } else {
        //换取 License 失败
        Toast.makeText(MainActivity.this, "License 获取失败, code: " + code, Toast.LENGTH_LONG).show();
    }
});
获取 License 时,ZEGO 服务端返回信息及处理建议
参数名 类型 说明 处理建议
Code
unsigned int32
通过客户端发送请求时,ZegoAvatar 服务端返回的错误码,取值如下:

  • 0:成功。
  • 1:参数有误。
  • 2:Token 有误。
  • 3:证书无效。
  • 4:服务内部问题。
  • 1:请检查您的输入参数 AppID 是否正确, AuthInfo 是否为空。
  • 2:AuthInfo 获取不正确,请联系 ZEGO 技术支持处理。
  • 3:AppId 没有配置可用的包名(Android)或 BundleID(iOS),请联系 ZEGO 商务人员确认。
  • 4:请联系 ZEGO 技术支持处理。
Message
string
返回的提示信息,和 “Code” 的取值相对应。

  • 0:Success
  • 1:Invalid argument
  • 2:Invalid token
  • 3:No valid license
  • 4:Service unavailable
Data
object
“Code” 为 0 时,返回鉴权文件的内容;“Code ”返回其它值时,表示获取鉴权失败,Data 为空。
License
string
鉴权文件的内容。

更多在线鉴权内容,请参考 在线鉴权

2 初始化 ZegoAvatarService

  1. 初始化 AvatarService 之前,请先导入以下代码,准备基础工作。

    import com.zego.avatar.OnRecordStartCallback;
    import com.zego.avatar.OnRecordStopCallback;
    import com.zego.avatar.ZegoAvatarService;
    import com.zego.avatar.ZegoAvatarView;
    import com.zego.avatar.bean.ZegoGenderType;
    import com.zego.avatar.bean.ZegoAvatarQualityLevel;
    import com.zego.avatar.bean.ZegoAvatarServiceState;
    import com.zego.avatar.bean.ZegoExpressionDetectMode;
    import com.zego.avatar.bean.ZegoModelType;
    import com.zego.avatar.bean.ZegoServiceConfig;
  2. 导入后,调用 init 接口,传入之前获取到的鉴权 License 字符串,初始化 AvatarService。

    // 先把资源拷贝到 SD 卡,注意:线上使用时,拷贝前添加判断逻辑,避免多次拷贝。资源也可以从网络上动态下载。
    AssetsFileTransfer.copyAssetsDir2Phone(this.getApplication(),
                "AIModel.bundle"/*apk 里的 assets 根目录*/, "assets"/* sd 卡里的目录, 值为:getFilesDir().getAbsolutePath() + File.separator + destPath */);
    AssetsFileTransfer.copyAssetsDir2Phone(this.getApplication(),
                "base.bundle", "assets");
    AssetsFileTransfer.copyAssetsDir2Phone(this.getApplication(),
                "Packages", "assets");
    
    String license = zegoLicense; // 从鉴权服务器 [步骤 1.3] 获取到的 license
    String AIPath = getFilesDir().getAbsolutePath() + "/assets/AIModel.bundle"; //   AI 模型的绝对路径
    ZegoServiceConfig config = new ZegoServiceConfig(license, AIPath);
    ZegoAvatarService.init(AvatarApplication.this, config);
  3. 注册 onStateChange 回调,接收初始化状态的相关回调通知。

    // AvatarService 初始化状态回调
    ZegoAvatarService.addServiceObserver(new ZegoAvatarServiceDelegate(){
        @Override
        public void onError(ZegoAvatarErrorCode code, String desc) {
            mMainHandler.post(() ->{
                ZALog.e("errorcode : " + code.getErrorCode() + ",desc : " + desc);
            });
        }
    
        @Override
        public void onStateChange(ZegoAvatarServiceState state) {
            // init 的状态回调。1. 成功或者失败的消息回调可能会收到多次; 2. 如果在 Activity 中注册该回调,请注意回收以防止内存泄露。
        }
    });

3 创建虚拟形象

在创建虚拟人物形象时,为了简化 Character(虚拟人物形象)的初始化、序列化、数据缓存、路径拼接等功能的接入流程,ZEGO Avatar SDK 提供了 ZegoCharacterHelper 类(开源),帮助开发者快速创建人物虚拟形象,详情请参考 ZegoCharacterHelper 使用说明

初始化 AvatarService 后,通过创建 ZegoCharacterHelper 对象,传入虚拟人物形象的外观数据(捏脸、换装、妆容等),设置视图参数(宽、高、位置等),创建一个虚拟形象。

public class AvatarMainActivity extends BaseActivity implements ZegoAvatarServiceDelegate {
    private ZegoAvatarView mZegoAvatarView;
    private IZegoInteractEngine mZegoInteractEngine;
    private ZegoCharacterHelper mCharacterHelper;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // ZegoAvatarService 初始化完成后
        ZegoAvatarService.addServiceObserver(this);
        mZegoAvatarView = findViewById(R.id.zego_avatar_view);
    }

    @Override
    public void onStateChange(ZegoAvatarServiceState state) {
        if (state == ZegoAvatarServiceState.InitSucceed) {
            AvatarMainActivity.this.runOnUiThread(() -> {
                // 创建 Helper 简化调用
                mCharacterHelper = new ZegoCharacterHelper(getFilesDir().getAbsolutePath() + "/assets/base.bundle"); // 基础资源的绝对路径

                mCharacterHelper.setExtendPackagePath(getFilesDir().getAbsolutePath() + "/assets/Packages"); // 设置妆容、头发、眼镜等资源包所在目录
                // 设置默认形象,可选 "male" 和 "female"
                mCharacterHelper.setDefaultAvatar("female");

                // 角色上屏,需要在 UI 线程调用,请保证上屏之前设置过正确的 AvatarJson 数据,即调用过 setDefaultAvatar 或 setAvatarJson 方法。
                mCharacterHelper.setCharacterView(mZegoAvatarView);

                //创建 AI 随动模型
                // !!!注意:此时需要相机或者语音权限,请参考 [集成 SDK] 文档设置权限
                mZegoInteractEngine = ZegoAvatarService.getInteractEngine();
                if (mZegoInteractEngine != null) {
                    //开启人脸随动
                    mZegoInteractEngine.startDetectExpression(ZegoExpressionDetectMode.Camera,expression -> {
                        zegoCharacter.setExpression(expression);
                    });
                }
            });
            ZegoAvatarService.removeServiceObserver(this);
        }
    }
}

如果用户不使用默认形象,想要根据图片自动生成定制化的虚拟形象,请参考 AI 捏脸

其它操作

虚拟形象创建完成后,可体验 Avatar 相关功能: