# 用户接入

平台针对用户提供的能力皆需要通过APPID+AppKey的方式鉴权通过后方可使用，因此使用AIGC视频和内容生成平台前，请您准备好平台账号。平台账号提供回调地址配置功能，这一功能使得在长时间任务完成时能够通过调用用户提供的API来完成消息的通知。

# 账号介绍

账号开通
- 目前用户账号尚不支持自注册服务，您可以联系运营提供您的基础信息（联系人/联系方式/企业信息等）。由运营开通账号并进行相关内容配置。
获取账号信息
- 用户的账号信息包括基础信息和资源配置两部分内容，可以通过我们提供的API接口来实时获取最新的信息内容。
  - 基础信息：包括账户ID，企业名称，服务有效期的起止时间以及APPID和AppKey信息。
  - 资源配置：包括可生成人物形象模型总可用量，可生成人物形象模型数总已用量，可生成TTS个人音色模型数总可用量，可生成TTS个人音色模型数总已用量，可生成视频时长总可用量，可生成视频时长总已用量，人物形象模型最大并发任务数总可用量，人物形象模型最大并发任务数总已用量，TTS个人音色模型生成最大并发任务数总可用量，TTS个人音色模型生成最大并发任务数总已用量，视频生成最大并发任务数总可用量，视频生成最大并发任务数总已用量等信息。
用户鉴权
- 平台提供为各系统在身份合法性校验环节获取令牌的接口。通过appId、时间戳、appKey加密生成得到的签名来完成用户鉴权，鉴权通过即可使用相关服务。
- 用户调用平台全部API服务，皆需要访问服务接入点：aigc.softsugar.com，并在请求头中加上token信息（token通过appId、时间戳、appKey加密生成得到的签名【MD5（appId+时间戳+appKey）】，MD5结果取32位小写值。后续接口都需要加上该token进行请求，添加方式为 Header: Authorization: Bearer {token}）。

# API 说明

# 三方系统接入登录

# 接口描述

用来为各系统在身份合法性校验环节获取令牌的接口。通过appId、时间戳、appKey加密生成得到的签名【MD5（appId+时间戳+appKey）】，MD5结果取32位小写值。后续接口都需要加上该token进行请求，添加方式为 Header: Authorization: Bearer {token}

# 请求地址

POST /api/uc/v1/access/api/token

# 请求头

Content-Type: application/json

# 请求参数

JSON数组格式，数组中对象的字段定义如下：

字段	类型	必填	描述
`appId`	String	True	app id （用户接入鉴权使用ID）
`timestamp`	String	True	当前时间戳，精确到毫秒
`sign`	String	True	生成的签名（MD5计算后的值转成十六进制字符串的形式，注意每个字节转换后的位数如果不足，请前面补零）
`grantType`	String	True	认证类型(固定值‘sign’)

# 请求样例

{
  "appId": "ID",
  "timestamp": "1676797061518",
  "sign": "c4b08ca7d242939b8bf9c1dbb1a1911a",
  "grantType": "sign"
}

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	Object	True	数据对象，错误返回null
- `permissions`	Obejct[]	True	权限对象数组
- `roles`	Obejct[]	True	角色对象数组
- `accessToken`	String	True	访问凭证，默认有效期8小时，有效期内多次获取仍会返回原token
- `expiresIn`	Integer	True	访问凭证剩余生命周期，单位：秒
- `refreshToken`	String	True	Refresh Token
- `refreshTokenExpiresIn`	Integer	True	refreshToken剩余生命周期，单位：秒
- `user`	Obejct	True	用户对象信息

permissions

字段	类型	必填	描述
`id`	Long	True	权限id
`appId`	Long	True	系统应用id
`resourceId`	Integer	True	资源 id
`action`	Integer	True	权限类型 (0: 所有, 1: 创建, 2: 修改 ,3: 删除, 4: 查询)
`creator`	Long	True	创建者id
`createTime`	String	True	创建时间, yyyy-MM-dd HH:mm:ss

roles

字段	类型	必填	描述
`id`	Long	True	角色id
`roleName`	String	True	角色名称
`appId`	Long	True	系统应用id
`description`	String	False	描述
`isDelete`	Integer	True	删除标记 (0: 未删除; 1: 已删除)
`creator`	Long	True	创建者id
`createTime`	String	True	创建时间, yyyy-MM-dd HH:mm:ss
`updater`	Long	True	更新者id
`updateTime`	String	True	更新时间, yyyy-MM-dd HH:mm:ss

user

字段	类型	必填	描述
`id`	Long	True	用户id
`userName`	String	True	用户名称
`profilePhoto`	String	False	个人照片
`company`	String	False	公司名称
`companyPhone`	String	False	公司电话
`companyContact`	String	False	公司联系地址
`status`	Integer	True	account status (0: 未开放; 1: 已启用; 2: 已禁用)
`effectiveBeginDate`	Date	True	生效开始时间, yyyy-MM-dd HH:mm:ss
`effectiveEndDate`	Date	True	生效结束时间, yyyy-MM-dd HH:mm:ss
`extraInfo`	String	False	附加信息
`description`	String	False	描述
`appId`	String	True	app id
`appKey`	String	True	app key
`licensePath`	String	False	license路径
`isDelete`	Integer	True	删除标记 (0: 未删除; 1: 已删除)
`creator`	Long	True	创建者id
`createTime`	String	True	创建时间, yyyy-MM-dd HH:mm:ss
`updater`	Long	True	更新者id
`updateTime`	String	True	更新时间, yyyy-MM-dd HH:mm:ss

# 响应样例

{
    "code": 0,
    "message": "success",
    "data": {
        "permissions": [
			{
                "id": 1,
                "appId": "虚拟人应用",
                "resourceId": 1,
                "action": null,
                "creator": 1,
                "createTime": "2022-05-23 15:12:35"
            }
		],
        "roles": [
            {
                "id": 3,
                "roleName": "企业",
                "appId": 1,
                "description": null,
                "isDelete": 0,
                "creator": 1,
                "createTime": "2022-05-23 15:12:35",
                "updater": 1,
                "updateTime": "2022-05-23 15:12:35"
            }
        ],
        "accessToken": "ZGI3YzRiZmY4ZmFjMjM2MDExODUxNDdmY2MwNGY4OTA0NGRmNGNjYi1jNGNmLTRlMTEtOTExOC05YTU0YTM2NjFjODY",
        "user": {
            "id": 4,
            "userName": "企业1",
            "profilePhoto": null,
            "company": null,
            "companyPhone": null,
            "companyContact": null,
            "status": 1,
            "effectiveBeginDate": null,
            "effectiveEndDate": null,
            "extraInfo": null,
            "description": null,
            "appId": null,
            "appKey": null,
            "licensePath": null,
            "isDelete": 0,
            "creator": 1,
            "createTime": "2022-05-23 15:13:03",
            "updater": 1,
            "updateTime": "2022-05-24 14:26:05"
        }
    }
}

# 用户Token刷新

# 接口描述

主动刷新用户Access Token，获取新的Access Token和Refresh Token，重新计算Access Token有效时间。注意：调用此接口Authorization的参数值应为Refresh Token。每两次调用token刷新接口的时间间隔不得低于3小时，否则提示“refresh token过于频繁,限制间隔3小时”。

# 请求地址

POST /api/uc/v1/access/api/token/refresh

# 请求头

Content-Type: application/json Header: Authorization: Bearer {refresh token}

# 请求参数

字段	类型	必填	描述
`appId`	String	True	app id （用户接入鉴权使用ID）
`grantType`	String	True	认证类型(固定值‘refreshToken’)

# 请求样例

{
  "appId": "APP ID",
  "grantType": "refreshToken"
}

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	Object	False	数据对象，错误返回null
- `accessToken`	String	True	访问凭证，默认有效期8小时
- `expiresIn`	Integer	True	访问凭证剩余生命周期，单位：秒
- `refreshToken`	String	True	Refresh Token
- `refreshTokenExpiresIn`	Integer	True	refreshToken剩余生命周期，单位：秒

# 用户登出

# 接口描述

用户登出系统时完成一些缓存信息清理工作。

# 请求地址

POST /api/uc/v1/web/logout

# 请求头

Content-Type: application/json

# 请求参数

无

# 请求样例

无

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	Object	False	成功与否，成功是1，错误返回null

# 响应样例

{
    "code": 0,
    "message": "success",
    "data": 1
}

# 获取账户基础信息和资源配置信息

# 接口描述

管理员创建账号时填写一系列基础信息和资源配置信息，此部分信息支持用户获取,此接口为通过账户ID获取账户基础信息和资源配置及使用情况。。

# 请求地址

GET /api/2dvh/v1/user/config/resource?userId={userId}

# 请求头

Content-Type: application/x-www-form-urlencode

# 请求参数

字段	类型	必填	描述
`userId`	Long	True	账户id

# 请求样例

https://xxx.softsugar.com/api/2dvh/v1/user/config/resource?userId=2

# 响应元素

字段	类型	必填	描述
`code`	Integer	True	0 - 成功, 其他 - 异常
`message`	String	True	异常详细信息
`data`	Object	False	数据对象，错误返回null
- `basicInfo`	Obejct	True	账户基础信息
- `resourceConfig`	Obejct	True	账户资源配置及使用信息

基础信息

字段	类型	必填	描述
`id`	Integer	True	id
`company`	String	True	企业名称
`effectiveBeginDate`	Date	True	服务有效期开始时间, yyyy-MM-dd HH:mm:ss
`effectiveEndDate`	Date	True	服务有效期结束时间, yyyy-MM-dd HH:mm:ss
`appId`	String	True	APP id（用户接入鉴权使用ID）
`appKey`	String	True	APP key

资源配置及使用量信息

字段	类型	必填	描述
`id`	Long	True	id
`genCharModelTotalQty`	Integer	True	可生成人物形象模型数总可用量
`genCharModelUsageQty`	Integer	True	可生成人物形象模型数总已用量
`genTtsCharVoiceModelTotalQty`	Integer	True	可生成TTS个人音色模型数总可用量
`genTtsCharVoiceModelUsageQty`	Integer	True	可生成TTS个人音色模型数总已用量
`genVideoDurationTotalQty`	Integer	True	可生成视频时长总可用量
`genVideoDurationUsageQty`	Integer	True	可生成视频时长总已用量
`charModelMaxConTasksTotalQty`	Integer	True	人物形象模型最大并发任务数总可用量
`charModelMaxConTasksUsageQty`	Integer	True	人物形象模型最大并发任务数总已用量
`ttsCharVoiceModelMaxConTasksTotalQty`	Integer	True	TTS个人音色模型生成最大并发任务数总可用量
`ttsCharVoiceModelMaxConTasksUsageQty`	Integer	True	TTS个人音色模型生成最大并发任务数总已用量
`videoGenMaxConTasksTotalQty`	Integer	True	视频生成最大并发任务数总可用量
`videoGenMaxConTasksUsageQty`	Integer	True	视频生成最大并发任务数总已用量

# 响应样例

{
    "code": 0,
    "message": "success",
    "data": {
		"resourceConfig": {
            "id": 1,
            "company": "zhangsan",
            "effectiveBeginDate": "2019-01-01 20:20:20",
            "effectiveEndDate": "2019-01-01 20:20:20",
            "appId": "7sadf7sadf7ads7f7asf7sda7f",
            "appKey": "7sadf7sadf7ads7f7asf7sda7f"
        },
        "resourceConfig": {
            "id": 1,
            "genCharModelTotalQty": 12,
            "genCharModelUsageQty": 2,
            "genTtsCharVoiceModelTotalQty": 12,
            "genTtsCharVoiceModelUsageQty": 2,
            "genVideoDurationTotalQty": 21,
            "genVideoDurationUsageQty": 11,
            "charModelMaxConTasksTotalQty": 12,
            "charModelMaxConTasksUsageQty": 3,
            "ttsCharVoiceModelMaxConTasksTotalQty": 11,
            "ttsCharVoiceModelMaxConTasksUsageQty": 4,
            "videoGenMaxConTasksTotalQty": 11,
            "videoGenMaxConTasksUsageQty": 7
        }
    }
}

以上即为平台针对用户接入平台使用服务时需要进行的准备工作。

← 通用数据结构及平台规范公共素材获取 →