# 通用数据结构及平台规范
# 服务接入点
| 地域名称 | 公网接入地址 | VPC接入地址 |
|---|---|---|
| 华东 | aigc.softsugar.com |
# 人物模型视频采集规范
为了完美克隆人物形象，请在拍摄时遵照商汤数字人采集制作规范，内容包括视频、语音，用于2D数字人的训练和测试，具体参考：采集规范 (opens new window)以及视频素材自检单 (opens new window)。
精品数字人视频采集请参考：精品数字人采集说明 (opens new window)。
# 视频合成参数输入规范
创建视频合成任务需要传入正确的param信息，其中包括各类视频合成参数（该参数为json转义后的字符串），请参考参数说明和 json 示例 以及示例效果 (opens new window) 。
# 直播参数输入规范
创建直播任务需要传入正确的param信息，其中包括各类参数（该参数为json转义后的字符串），请参考直播脚本json 定义说明和示例以及直播接管 json 定义说明和示例 。
# web-js代码部分示例
为了方便web端客户更方便地了解API的接入和使用形式，提供部分功能模块的web-js代码部分示例，包括：直播创建、直播接管、直播关闭、创建人物模型生成/更新任务并查询任务状态、创建视频合成任务并查询任务状态、创建TTS音色模型生成任务并查询任务状态等，具体请参考代码示例 (opens new window)。
# 公共返回参数
所有接口均返回以下结构数据，具体业务内容在data字段中返回。
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
code | Integer | True | 状态码 |
message | String | True | 错误消息 |
data | Object | False | 返回数据 |
# 分页信息
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
pageNo | Integer | True | 当前页码 |
numberPages | Integer | True | 总页数 |
numberRecords | Integer | True | 总记录数 |
pageSize | Integer | True | 每页条数 |
startIndex | Integer | True | 当前页的起始索引 |
# HTTP回调事件通知
本文为您介绍HTTP回调事件通知的回调机制、使用流程及鉴权原理。
# HTTP回调机制
您需要自行部署一个HTTP服务来接收回调消息，并在提供回调URL，平台将进行相应配置。 当事件产生时，PAAS服务端会向该URL发起HTTP POST请求，事件通知内容将通过HTTP Body送达。 您的HTTP服务对HTTP POST请求进行签名认证鉴权，鉴权成功则响应状态码200即视为回调成功，若响应其他状态码或响应超时则视为回调失败。鉴权原理请参见HTTP回调鉴权原理。 回调成功后，您配置的回调URL中将接收到相应的事件通知内容。回调失败后，点播服务会继续重试回调2次，即总共最多回调3次；超过3次后则会丢弃本次回调事件通知。
# HTTP回调鉴权原理
PAAS服务支持在HTTP（含HTTPS）回调时增加特定签名头，供回调消息接收服务端进行签名认证，以防止非法或无效请求。
# 注意事项
HTTP回调鉴权是否开启由您自行决定（建议开启）。一旦设置了AuthKey（鉴权密钥），则回调时会携带所有鉴权相关内容，供回调消息接收服务端进行鉴权使用，即设置AuthKey不会影响原有功能，具体是否校验由您自行决定。 如果未设置AuthKey，也不会受任何影响。
# 鉴权参数
在回调HTTP消息体增加的具体鉴权参数如下
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
timestamp | Integer | False | UNIX时间戳，整型正数，固定长度10，1970年1月1日以来的秒数，表示回调请求发起时间。 |
signature | String | False | 签名字符串，为32位小写MD5值，详细说明请参见下文签名算法。（MD5计算后的值转成十六进制字符串的形式，注意每个字节转换后的位数如果不足，请前面补零） |
# 签名算法
signature的计算依赖如下字段：
| 字段 | 示例 | 描述 |
|---|---|---|
回调URL | https://www.example.com/your/callback | 用户设置的回调地址。 |
timestamp | 1693206851 | UNIX时间戳，整型正数，固定长度10，1970年1月1日以来的秒数，表示回调请求发起时间。 |
AuthKey | abc123 | 用户提供的鉴权Key，最长32位，必须同时包含大写字母、小写字母和数字。 |
将上述三个字段进行拼接后计算MD5值，即：
MD5Content = 回调URLtimestampAuthKey
signature = md5sum(MD5Content)
signature字段计算方法示例如下：
signature = md5sum(https://www.example.com/your/callback1693206851abc123) = 863151b586912152aacee3124f81e301
# 回调消息接收服务端校验规则
- 回调消息接收端将回调所设置的回调URL、timestamp、AuthKey字符串拼接后，进行MD5值计算，得到加密串，再将加密串与signature字段进行对比，如果不一致，则请求非法。
- 回调消息接收端获取当前时间，与回调请求所带的timestamp字段时间相减，如果超过回调消息接收服务端所设定的指定时间（如5分钟，由回调消息接收服务端自行定义），则认为该请求无效。
# AuthKey切换
用户在切换AuthKey时，为保证回调功能不受影响，回调消息接收服务端需要兼容新旧两个AuthKey的平滑切换，即在一段时间内兼容新旧两个AuthKey的鉴权，由回调消息接收服务端完成。
建议操作顺序如下：
- 用户定义新的AuthKey。
- 用户升级回调消息接收服务端，兼容新、旧两个AuthKey的鉴权。
- 在点播控制台将AuthKey更新成最新。
- 观察一段时间后，回调消息接收服务端去掉对原来旧AuthKey的兼容。
- 切换完成。
# HTTP回调使用方法
# 前提条件
- 您已部署用于接收回调消息的HTTP/HTTPS服务。
# 错误信息描述
| 错误代码 | 描述 |
|---|---|
| 0 | 成功 |
| 400 | 错误 |
| 500 | 错误 |
| 10101001 | iam 身份 ID 无效。 |
| 10999999 | 接入中心异常 |
| 20999999 | 生成平台异常 |
| 30999999 | 数字资产平台异常 |
| 50101503 | 解析授权错误 |
| 50101504 | 授权不存在 |
| 50102101 | 手机号不能为空 |
| 50102102 | 手机号不合法，必须是11位真实手机号 |
| 50102103 | 验证码不能为空 |
| 50102104 | 验证码不合法 |
| 50102105 | 验证码已失效 |
| 50102106 | 账户名不能为空 |
| 50102107 | 账户名不合法，必须是合法的邮箱或手机号 |
| 50102108 | 密码不能为空 |
| 50102109 | 账户或密码错误 |
| 50102110 | 用户名称不能为空 |
| 50102111 | 企业信息不能为空 |
| 50102112 | 邮箱不能为空 |
| 50102113 | 密码必须使用字母、数字和符号两种及以上的组合，6-16个字符，区分大小写 |
| 50102114 | 用户名称最大长度25个字符 |
| 50102115 | 企业信息最大长度50个字符 |
| 50102116 | 邮箱最大长度80个字符 |
| 50102117 | 密码不一致 |
| 50102118 | 发送验证码失败 |
| 50102119 | 邮箱的地址规则：数字、字母、下划线 + @ + 数字、英文 + . +英文（长度是2-4） |
| 50102120 | 修改密码出错 |
| 50102121 | 新建账户失败 |
| 50102122 | 获取账户信息失败 |
| 50102123 | 无效的验证码类型 |
| 50102124 | 邮箱已存在 |
| 50102125 | 账户id必须大于0 |
| 50103201 | 订单不存在 |
| 50103202 | 在企业端如果要恢复订单，当前状态必须是 已取消 |
| 50103203 | 在管理端不是管理员删除的 |
| 50103204 | 如果要删除订单，当前状态必须是 已取消 |
| 50103205 | 如果要取消订单，当前状态必须是 已催办/待处理/处理中 |
| 50103206 | 如果要催办订单，当前状态必须是 已催办/待处理/处理中 |
| 50103207 | 以上特效已经下架，无法生成订单，请清理后重新下单 |
| 50103208 | 生成的订单包含的特效数量不能为0 |
| 50103209 | 24小时内不可重复催办 |
| 50103210 | 只有管理员才能做此操作 |
| 50103211 | 已删除的订单不能修改状态 |
| 50103212 | 管理员不能查看已取消的订单 |
| 50103213 | 管理员才能查看订单详情 |
| 50103214 | 管理员不能创建订单 |
| 50103215 | 无效的订单状态 |
| 50103216 | 无效的订单排序名称 |
| 50103217 | 只有企业账户才能催办 |
| 50103218 | 只有企业账户才能取消 |
| 50104401 | 特效标签存在关联的特效 |
| 50104402 | 特效标签名重复 |
| 50105301 | 文件key/有效时间不合法 |
| 50105302 | 文件上传失败 |
| 50105303 | 文件下载失败 |
| 50105304 | 文件删除失败 |
| 50105305 | 未获取输入流 |
| 50105306 | S3文件不存在 |
| 50105307 | 压缩S3文件异常 |
| 50106403 | 特效压缩包解压异常 |
| 50106404 | 特效压缩包解析异常 |
| 50106405 | 特效压缩包加密异常 |
| 50106406 | 特效压缩包JSON文件不存在 |
| 50106407 | 特效处于使用中，无法删除 |
| 50106703 | 无效的排序名称 |
| 50107601 | 不合法的app_id |
| 50107603 | 不合法的签名 |
| 50107604 | data数据格式非法 |
| 50107607 | data数据解密失败 |
| 50107605 | 找不到APP key |
| 50107606 | 找不到SDK key |
| 60102101 | 手机号不能为空 |
| 60102102 | 手机号不合法，必须是11位真实手机号 |
| 60102103 | 验证码不能为空 |
| 60102108 | 密码不能为空 |
| 60102112 | 邮箱不能为空 |
| 60102116 | 邮箱最大长度80个字符 |
| 60102119 | 邮箱的地址规则：数字、字母、下划线 + @ + 数字、英文 + . +英文（长度是2-4） |
| 60102123 | 无效的验证码类型 |
| 60102124 | 邮箱已存在 |
| 60102126 | 账户不存在 |
| 60102127 | 请输入邮箱或手机号 |
| 60102128 | 账户待开通 |
| 60102129 | 该帐号已停用，如需使用请联系管理员启用账号 |
| 60102130 | 连续登录%s次失败，请%s后重试 |
| 60102131 | 生成RSA密钥对异常 |
| 60102132 | 密钥对生成失败！ |
| 60102133 | 公钥不能为空 |
| 60102134 | RSA获取私钥异常 |
| 60102135 | 公钥已过期，请重新生成 |
| 60102136 | 解密发生错误 |
| 60102137 | RSA解密异常 |
| 60102138 | 密码不正确 |
| 60102139 | 手机号已存在 |
| 60102140 | 用户状态不正常 |
| 60102141 | 角色已存在 |
| 60102142 | 用户角色关系已存在 |
| 60102143 | 角色权限关系已存在 |
| 60102144 | 发送邮件%s失败 |
| 60102145 | 服务有效期区间不合理 |
| 60102146 | 没有权限进行该参数对应的业务(请核实该用户是否存在，用户参数是否冲突，状态是否正常，角色关系数据是否合理等等) |
| 60102147 | 新建角色个数必须大于0 |
| 60102148 | 导出角色个数必须大于0 |
| 60102149 | 服务有效期开始时间不能为空 |
| 60102150 | 服务有效期结束时间不能为空 |
| 60102151 | appId不能为空 |
| 60102152 | appKey不能为空 |
| 60102153 | 新密码不能为空 |
| 60102154 | 此应用下没有绑定角色 |
| 60102155 | 新建角色个数和导出角色个数不能为空 |
| 60102156 | 账户不在有效期内 |
| 60102157 | appId已存在 |
| 60102158 | appId和appKey不匹配 |
| 60102159 | 请输入2-8位中英文联系人姓名 |
| 60111101 | APP不存在 |
| 60111301 | APP不存在 |
| 60112505 | 访问授权过期，请重新登录 |
| 60112160 | 第三方系统验签失败 |
| 60112161 | refresh token过于频繁,限制间隔%s小时 |
| 60112162 | grant type不合法 |
| 70107701 | 标签正在被使用 |
| 70107702 | 系统标签无法修改、删除 |
| 70104703 | 标签名称不能为空 |
| 70104704 | 标签类型不能为空 |
| 80107807 | 当前算法状态禁止重启启动 |
| 80107811 | 请求虚拟人服务异常 |
| 80108801 | OPEN FEIGN 请求来源不合法 |
| 80108802 | 注册中心不存在上线状态的算法工作节点实例 |
| 80108803 | 该算法工作节点实例在注册中心不是上线状态 |
| 80108804 | 注册中心没有算法工作节点实例 |
| 80108805 | 算法工作节点实例协商失败 |
| 80108806 | 算法调度服务调用虚拟人服务接口获取卡通风格集合失败 |
| 80108810 | 算法调度服务调用虚拟人服务接口获取卡通风格及其下载地址集合失败 |
| 80109809 | 工作节点没有可用的空闲任务资源可用于调度，请稍后再试 |
| 80109814 | 调度命令不存在 |
| 80109815 | 请求算法服务异常 |
| 80109817 | dispatcher不支持worker的算法 |
| 80109833 | 当前算法任务在调度中心状态异常 |
| 80117823 | 负载值不合法或为空。 |
| 80117824 | 没有使用此 gan 算法类别的worder。 |
| 80117825 | 此功能未在商业服务中注册。 |
| 80117826 | 拉取整个分类功能配置错误。 |
| 80117827 | 功能-zip 映射不存在。 |
| 80115947 | 当前服务资源已达到上限，无法创建直播，请稍后再试 |
| 80115950 | 无历史参数记录，不支持更新，需要重新生成模型 |
| 80115962 | 您的试用账号直播已达到使用上限：%s路，无可用资源，请稍后再试 |
| 80115963 | 您的正式账号直播已达到使用上限：%s路，无可用资源，请稍后再试 |
| 80115964 | 直播服务已达到可用资源上限，无可用资源，请稍后再试 |
| 80115983 | 已创建的%s任务数量已达到当前账号任务并发上限数量限制，请稍候再试 |
| 81107808 | 算法工作节点不支持创建的线程类型 |
| 81114812 | 虚拟人卡通角色sdk创建avatar失败 |
| 81114813 | 虚拟人卡通角色sdk handler资源耗尽，请稍后再试 |
| 81114816 | 找不到style |
| 81117819 | Bling sdk创建gan特效句柄失败 |
| 81117820 | 图片大小不能超过5M |
| 81117821 | sdk 任务正在运行 |
| 81117822 | 函数值不合法。 |
| 81117828 | 属性编辑功能-zip 映射配置不存在。 |
| 81118829 | AvatarPackage Handler 异常 |
| 81118830 | AvatarPackage Handler创建异常，错误code |
| 81118831 | AvatarPackage Handler License验证失败，错误code |
| 81118832 | AvatarPackage Handler Process失败，错误code |
| 81118836 | AvatarPackage FBX 不支持压缩 |
| 81118837 | AvatarPackage JSON 格式异常 |
| 81118838 | 素材文件缺失必要类型文件，无法生成角色FBX/GLB文件 |
| 81118839 | AvatarPackage Handler 处理中，请稍后再试 |
| 82116818 | 任务id不能为空 |
| 83119834 | 无空闲视频生成 worker |
| 83119308 | 文件解压异常 |
| 83115905 | 账号id不能为空 |
| 83115906 | 启动2D数字人算法任务失败 |
| 84115913 | 视频生成人物模型格式有误，须为zip格式，且包含assets和models资源 |
| 84115914 | 视频任务风格化数据输入格式非法，仅支持视频格式:mp4/csv/vid/ebm/mov，图片格式:jpg/JPG/jpeg/JPEG/png/bmp |
| 83115920 | 启动2D数字人直播算法任务失败 |
| 83115921 | 停止2D数字人直播算法任务失败 |
| 83115922 | 初始化2D数字人直播算法任务失败 |
| 83115923 | 接管2D数字人直播算法任务失败 |
| 83115924 | 直播视频生成人物模型格式有误，须为zip格式，且包含assets和models资源 |
| 83115951 | background/foreground中url中文件格式不符合type要求，0(jpg,jpeg,png,gif,bmp,tiff,svg)，1(mp4,avi,mov,wmv,flv,mkv) |
| 83115952 | 初始化失败 |
| 83115961 | urtcUid需为不超过32位uint长度的纯数字 |
| 83115965 | urtcUseExternalApp为true时，urtcToken,urtcAppId,urtcChannelId,urtcUid为必填 |
| 83115971 | 直播接管列表重排失败 |
| 83115972 | 获取直播接管列表失败 |
| 83115973 | 加入直播列表失败 |
| 83115977 | 直播接管初始化中,不支持重排 |
| 84115912 | 可生成人物形象模型数已用量大于总量后不能生成人物形象模型任务 |
| 84115915 | 直播初始化尚未完成，请稍等 |
| 84115916 | 直播已开启，请勿再次开启 |
| 84115917 | 直播任务异常，无法开启 |
| 84115918 | 直播任务未进行，无法接管 |
| 84115919 | 直播任务已完成或者状态异常，无需关闭 |
| 84999920 | 请符合以下参数规则：assetScale可选，默认值是1.0，取值范围是0.1到3；assetStart和assetEnd可选，并且成对儿出现，都不能为负数，assetEnd要大于assetStart；greenParamsSpillByalpha 范围为0.3到0.7, greenParamsBlurKs 大于等于1，且为奇数 |
| 84115921 | 当前直播接管异常 |
| 84115922 | 当前直播正在接管中，请稍后再试 |
| 84115923 | 当前直播已经关闭，无法开启 |
| 84115925 | 当前用户没有权限执行此操作 |
| 84115926 | 当前连接因失联超过10min，请重连 |
| 84115927 | 请求参数不合法 |
| 84115928 | 资源路径无效 |
| 84115929 | 任务/会话不存在 |
| 84115930 | 直播正在进行中 |
| 84115931 | 接管出错，未知原因 |
| 84115932 | 直播可查状态为：5(完成)，9(异常) |
| 84115933 | 直播已开启，channel Id为%s |
| 84115934 | 直播已初始化完成，channel Id为%s |
| 84115940 | 创建TTS个人音色模型生成任务失败 |
| 84115941 | 取消TTS个人音色模型生成任务失败 |
| 84115942 | 获取TTS个人音色模型任务详情失败 |
| 84115935 | 视频生成JSON文件解析错误 |
| 84115943 | token不合法 |
| 84115945 | 直播初始化JSON文件解析错误 |
| 84115944 | 可直播时长已用量大于总量后不能新建直播任务 |
| 84115946 | 直播已经关闭，无法进行后续操作 |
| 84115948 | 当前剩余可分配路数为 %s (全部-公共保留-已设置之和)路,请调整.当前配置数>总可用数时,系统资源将发生抢占! |
| 84115949 | 只有等待中或进行中的任务可以取消 |
| 84115955 | 刷新rtcToken过于频繁, 限制间隔%s小时 |
| 84115956 | 当前直播会话无此channelId |
| 84115953 | 直播已关闭 |
| 84115957 | 该账户有正在直播中的任务，为避免造成异常影响，暂时不支持变更账户标签 |
| 84115958 | 可生成tts模型数已用量大于总量后不能生成tts模型任务 |
| 84115959 | 人物模型文件URL非法，或者不是zip格式 |
| 84115960 | 直播推送JSON文件解析错误 |
| 84115966 | 只有已取消或异常的任务才允许重新生成 |
| 84115967 | 账单明细中存在重复任务 %s |
| 84115968 | 没有获取到锁 %s. |
| 84115969 | 任务不存在或者状态不满足 |
| 84115970 | 管理员不能创建任务 |
| 84115974 | TTS个人音色模型优先级变更任务失败 |
| 84115975 | 可生成2k人物形象模型数已用量大于总量后不能生成2k人物形象模型任务 |
| 84115976 | 可生成4k人物形象模型数已用量大于总量后不能生成4k人物形象模型任务 |
| 84115975 | 已生成 2k 人物形象模型数量已达到当前账号总可用量限制，无法创建任务 |
| 84115976 | 已生成 4k 人物形象模型数量已达到当前账号总可用量限制，无法创建任务 |
| 84115979 | 已创建的声音克隆任务数量已达到当前账号任务并发上限数量限制，请稍候再试 |
| 84115980 | NLP APP不存在 |
| 84115981 | NLP Skill不存在 |
| 84115982 | 任务并发数量限制需要大于0 |
| 84115984 | 查询到%s条数据，数据量较大，请导出后查看。 |
| 89999998 | 请求限制键不允许为空 |
| 89999999 | 您的访问过于频繁，请稍后重试 |
| 90113801 | 该用户已达最大创建角色数 |
| 90113802 | 该用户已达最大导出角色数 |
| 90113803 | 验证创建角色数异常 |
| 90113804 | 获取原始材料异常 |
| 90113805 | 删除临时文件夹异常 |
| 90113806 | 角色生成异常，请根据要求检查上传图片或稍后重试 |
| 90113807 | 没有可用Handler |
| 90113808 | 更新JSON文件异常 |
| 90113809 | 算法返回失败 |
| 90113810 | SDK Aimodel文件路径不存在 |
| 90113811 | 请检查上传正确的人脸图后尝试重新生成 |
| 90113812 | 不支持的图像格式 |
| 90113813 | 文件格式不正确导致加载失败 |
| 90113815 | 请检查该角色风格的自动捏脸配置model |
| 90114814 | 仅支持jpg/png格式图片 |
| 90114833 | 角色不存在 |
| 90114834 | 更新过于频繁，请稍后再试 |
| 90114835 | 文件内容无法解析，请参考系统生成角色素材文件 |
| 90115901 | 优先执行任务失败 |
| 90115903 | 启动超写实算法任务失败 |
| 90115904 | 停止超写实算法任务失败 |
| 99999990 | 访问禁止 |
| 99999991 | 服务不可用 |
| 99999992 | Hystrix 错误请求 |
| 99999993 | Hystrix 运行异常 |
| 99999994 | Hystrix超时 |
| 99999995 | Feign错误 |
| 99999996 | 输入无效 |
| 99999997 | 网关错误 |
| 99999998 | 外部服务错误 |
| 99999999 | 错误 |
用户接入 →