定制小程序接口 - 阿里云Vlog产品说明

本服务仅适用于已部署阿里云Vlog基础设施的场景，开发者可以基于此API自定义面向C端用户的小程序、APP等，完成业务闭环。

更新时间	服务版本号	说明	备注
2021-2-5	1.0.0	初始版本，含用户注册、视频提取、数据分析等基本功能。	开发小程序的必需接口。
2021-4-15	“生成vlog”接口版本号升级至1.1.0	新增图片查询接口和二次编辑接口。	二次编辑接口属内测邀请接口，暂不支持全量开放。
2021-4-30	“查询vlog生成情况”接口版本号升级至1.1.0	新增状态码和合成进度。
2021-6-3	“查询vlog生成情况”接口版本号升级至1.2.0	支持返回摄像头ID和名称，可基于此信息做打卡点引导
2021-6-3	“查询景区列表”版本号升级至1.1.0	“景区详情接口”支持返回玩法视频的地址
2021-6-3	新增“获取足迹列表”，版本号1.0.0	新增“获取足迹列表”，可返回当前UID下全量合成的成品列表
2021-7-15	新增“获取景区模版列表”，版本号1.0.0	可返回当前景区的全量模板信息
2021-09-26	“查询vlog生成情况”接口版本号升级至1.3.0	支持同时返回最新和最佳视频
2021-09-26	“埋点服务”接口版本号升级至1.1.0	支持全链路埋点，了解流失情况

接口说明

服务开通及秘钥获取

参考账号开通和软件部署完成产品激活。
激活后，可通过实例总览页右方的秘钥调用本服务。

接入方式

SDK依赖

本例提供java sdk pom依赖示例，更多语言SDK详情请参考API调用对接指引

<dependency>
<groupId>com.aliyun.api.gateway</groupId>
<artifactId>sdk-core-java</artifactId>
<version>1.1.0</version>
</dependency>

示例代码

HttpClientBuilderParams builderParams =newHttpClientBuilderParams();
builderParams.setAppKey("${appKey}");// 请填写正确的AppKey
builderParams.setAppSecret("${appSecret}");// 请填写正确的AppSecret
ApacheHttpClient apacheHttpClient =newApacheHttpClient(builderParams);
IoTApiRequest request =newIoTApiRequest();
//设置api的版本
request.setApiVer("1.0.0");
//如果需要登录，设置当前的会话的token
//设置参数
request.putParam("model","xxxxxx");
request.putParam("projectId","yyyyy");

Map<String,Object> param =newHashMap<>(8);
param.put("startTime","2019-01-01");
param.put("endTime","2019-01-31");
param.put("limit",10);

request.putParam("paramJson",JSONObject.toJSONString(param));
//请求参数域名、path、request
String host ="api.link.aliyun.com";
String path ="/tourism/statistics/query";
System.out.println(JSON.toJSONString(request));
ApiRequest apiRequest =newApiRequest(HttpScheme.HTTP, host,
HttpMethod.POST_BODY, path, JSON.toJSONBytes(request));
apiRequest.setHttpConnectionMode(HttpConnectionModel.MULTIPLE_CONNECTION);
ApiResponse response = apacheHttpClient.sendSyncRequest(apiRequest);
System.out.println(request.getId());
System.out.println(
"response code = "+ response.getCode()+" response message = "+ response.getMessage()
+" response content = "+newString(response.getBody(),
"utf-8"));

接口详情

注册用户

path：/vlog/open/user/register

version：1.0.0

入参

参数名称	类型	是否必填	参数说明
nickName	String(20)	是	昵称
userId	String(64)	是	用户id
phone	String(11)	是	手机号
outUserId	String(64)	是	外部应用id，例如微信用户id，支付宝用户id
userType	String	是	ALIPAY-支付宝小程序，WECHAT-微信小程序，OTHER-其他
gender	integer	是	0-男，1-女

出参

字段名	类型	备注
code	String	异常码
message	String	异常原因
localizedMsg	String

查询景区列表

path：/vlog/open/case/list

version：1.0.0

入参：

参数名称	类型	是否必填	参数说明
pageNo	Integer	是	页号
pageSize	Integer	是	页大小

出参

字段名	类型	备注
id	String	request id
code	Integer	错误码，成功时返回200
message	String	错误描述，成功时返回"success"
localizedMsg	String	本地语言错误消息
data	JSON	结果数据
-total	Long	总数
-pageNo	Integer	页号
-pageSize	Integer	页大小
-items	List	景区列表
--caseId	String	景区id
--name	String	景区名称
--address	String	景区地址
--description	String	景区描述信息
--coverImgUrl	String	景区封面图
--showVideoUrl	String	景区展示宣传视频

查询景区详情

path：/vlog/open/case/detail

version：1.1.0

入参

参数名称	类型	是否必填	参数说明
caseId	String	是	景区id

出参

字段名	类型	备注
id	String	request id
code	Integer	错误码，成功时返回200
message	String	错误描述，成功时返回"success"
localizedMsg	String	本地语言错误消息
data	JSON	结果数据
-caseId	String	景区id
-name	String	景区名称
-address	String	景区地址
-location	JSON	景区地图坐标
--lat	Double	经度
--lon	Double	纬度
-description	String	景区描述信息
-coverImgUrl	String	景区封面图
-cameraPositions	List	打卡点列表
--name	String	打卡点名称
--location	JSON	打卡点地图坐标
---lat	Double	经度
---lon	Double	纬度
--thumbnailUrl	String	封面图地址
--description	String	点位描述
--playIntroduce	JSON	玩法视频
-vlogSamples	List	景区样片列表
--title	String	标题
--description	String	描述
--videoUrl	String	视频地址
--cover	String	封面图片
--duration	Long	视频时长

生成Vlog

path：/vlog/open/create

version：1.1.0

入参

参数名称	类型	是否必填	参数说明
caseId	String	是	景区id
userId	String	是	用户id
faceImgData	String	是	人脸图片base64编码
optimalFramesNum	Integer	是	最优帧数量，0-30（0表示不返回）返回的最优帧个数以结果为准，小于等于输入参数值
enableImgBeauty	Boolean	否	是否对最优帧美颜，true-是 false-否若最优帧数为0，该字段可不写；否则必须填写

出参

字段名	类型	备注
id	String	request id
code	Integer	错误码，成功时返回200
message	String	错误描述，成功时返回"success"
localizedMsg	String	本地语言错误消息
data	String	任务id

查询vlog生成情况

path：/vlog/open/status/query

version：1.3.0

入参

参数名称	类型	是否必填	参数说明
jobId	String	是	任务id
userId	String	是	用户id

出参

字段名	类型	备注
id	String	request id
code	Integer	错误码，成功时返回200
message	String	错误描述，成功时返回"success"
localizedMsg	String	本地语言错误消息
data	List	结果数据
-productId	String	作品id
-type	String	类型activity: 普通活动custom: 用户二次合成视频
-status	String	vlog状态composing：合成中done：完成failed：失败NEW_PREPARE_MATERIAL：素材准备中
-videoUrl	String	vlog视频地址
-templateId	String	作品使用的模板id
-thumbImageUrl	String	封面图地址
-duration	Long	vlog时长，单位毫秒
-caseId	String	景区id
-jobId	Stirng	任务id
-firstProductId	String	首次作品id
-faceNumber	Integer	合成模板中需要的人脸镜头数量
-progress	Integer	合成进度
-videoDetail	JSON	视频细节
--width	Integer	宽
--height	Integer	高
-lensExtra	List	摄像头信息
--deviceId	String	摄像头id
--deviceName	String	摄像头名称
-vlogLabel	String	vlog视频类型 optimal 最新的 newest 最优的

查询美颜照片生成进度

path：/vlog/open/image/status/query

version：1.0.0

入参

参数名称	类型	是否必填	参数说明
userId	String	是	用户id
jobId	String	是	vlog/美颜照片合成任务id

出参

字段名	类型	备注
id	String	request id
code	Integer	错误码，成功时返回200
message	String	错误描述，成功时返回"success"
localizedMsg	String	本地语言错误消息
data	List	结果数据
-productId	String	作品id
-jobId	String	任务id
-status	String	vlog状态composing：合成中done：完成failed：失败
-userId	String	用户id
-caseId	String	景区id
-imageUrl	String	最优帧图片地址

获取足迹列表

path：/vlog/open/order/list

version：1.0.0

入参

参数名称	类型	是否必填	参数说明
userId	String	是	用户id
size	Integer	是	一次返回的足迹数量（大于等于该数值）
endDate	Long	是	足迹的最近日期，从该日期向前获取数据（时间戳）
caseId	String	否	景区id

出参

字段名	类型	备注
id	String	request id
code	Integer	错误码，成功时返回200
message	String	错误描述，成功时返回"success"
localizedMsg	String	本地语言错误消息
data	List	结果数据
-productId	String	作品id
-type	String	类型activity: 普通活动custom: 用户二次合成视频
-tempalteId	String	作品使用的模版id
-status	String	vlog状态composing：合成中done：完成failed：失败NEW_PREPARE_MATERIAL：素材准备中
-thumbImageUrl	String	vlog封面图片地址
-videoDetail	JSON	视频详情
--width	Integer	宽
--height	Integer	高
-videoUrl	String	vlog视频地址
-duration	Long	vlog时长
-caseId	String	景区id
-jobId	String	任务id
-firstProductId	String	首个作品id
-faceNumber	Integer	合成模板中需要的人脸镜头数量
-progress	Integer	进度
-userId	String	用户id
-createDate	String	创建时间
-lensExtra	List	摄像头信息
--deviceId	String	摄像头id
--deviceName	String	摄像头名称

数据埋点

path：/vlog/open/data/backflow

version：1.1.0

入参

参数名称	类型	是否必填	参数说明
userId	String	是	终端用户id
action	String	是	详见“action列表”
time	Date	是	最晚日期，默认值为当前日期
productId	String	否	视频id 观看/VLOG_VIEW 下载/ VLOG_DOWNLOAD 分享/ VLOG_SHARE 支付/VLOG_PAID 以上四个事件，需要写该参数，用于准确计算当天运营数据
templateId	String	否	模版id 观看/VLOG_VIEW 下载/ VLOG_DOWNLOAD 分享/ VLOG_SHARE 支付/VLOG_PAID 以上四个事件，需要写该参数，用于准确计算当天运营数据

action分类

分类	action	说明
用户访问相关	APP_ACCESS	用户访问应用首页时使用
	CASE_LIST	查看景区列表时使用
	CASE_DETAIL	查看景区详情时使用
获取vlog相关	VLOG_CREATE	用户点击扫脸获取vlog时使用（点进去未进行扫脸）
	VLOG_CREATE_START	用户开始扫脸创建vlog时使用（进行扫脸）
	VLOG_GENERATE	用户扫脸创建的vlog成功生成时使用
	VLOG_IMAGE_GET	获取最优帧成功时使用
	VLOG_MOMENT_LIST	获取vlog精彩片段列表时使用
	VLOG_TEMPLATE_LIST	获取vlog模版信息时使用
	VLOG_RECOMPOSE	自定义创建vlog时使用
	VLOG_FOOTPRINT	获取vlog历史足迹列表时使用
vlog使用相关	VLOG_VIEW	用户播放vlog视频时使用
	VLOG_DOWNLOAD	用户下载保存vlog使用
	VLOG_SHARE	用户分享vlog时使用
vlog支付相关	ORDER_LIST	获取vlog订单时使用
vlog支付相关	VLOG_PAID	为vlog付费时使用（支付成功进行该数据埋点）

出参

字段名	类型	备注
id	String	request id
code	Integer	错误码，成功时返回200
message	String	错误描述，成功时返回"success"
localizedMsg	String	本地语言错误消息

获取景区模版列表

path ：/vlog/open/case/template/list

version：1.0.0

入参

参数名称	类型	是否必填	参数说明
caseId	String	是	景区id

出参

字段名	类型	备注
id	String	request id
code	Intteger	错误码，成功时返回200
message	String	错误描述，成功时返回"success"
localizedMsg	String	本地语言错误消息
data	List
-name	String	模版名称
-templateId	String	模版id

订单列表查询

说明

仅在使用“一录打卡”小程序并开通支付功能场景下使用

path：/vlog/open/order/list

version：1.0.2

入参

参数名称	类型	是否必填	参数说明
userId	String	否	终端用户id
orderId	String	否	订单id
productId	String	否	作品id
status	String	否	订单状态PAY_SUCCESS 支付成功FAIL 支付失败TIME_OUT_CLOSE 订单超时关闭EXECUTING 订单等待支付中
caseId	String	否	景区id
startDate	String	否	下单时间区间（开始，不包含）yyyy-MM-dd HH:mm:ss
endDate	String	否	下单时间区间（结束，不包含）yyyy-MM-dd HH:mm:ss
pageSize	Integer	是	页面大小
pageNo	Integer	是	页号

出参

字段名	类型	备注
code	String	异常码
message	String	异常原因
localizedMsg	String
data	JSON
-total	Long
-pageNo	Integer
-pageSize	Integer
-items	List
--orderId	String	订单id
--caseId	String	景区id
--userId	String	用户id
--productId	String	作品id
--orderAmount	Long	订单金额
--orderTime	String	订单时间
--status	Stirng	订单状态PAY_SUCCESS 支付成功FAIL 支付失败TIME_OUT_CLOSE 订单超时关闭EXECUTING 订单等待支付中

成品二次编辑服务

注意

此服务是邀请内测增值定制服务，涉及较多的页面开发，需额外授权，请和阿里云商务对接后开通。

查询作品精彩片段列表

path：/vlog/open/moment/list

version：1.0.0

入参

参数名称	类型	是否必填	参数说明
userId	String	是	用户id
caseId	String	是	景区id
productId	String	是	作品id

出参

字段名	类型	备注
code	String	异常码
message	String	异常原因
localizedMsg	String
data	List
-momentId	String	素材片段id
-mediaType	String	媒体类型，image, video
-status	String	状态unstart 未开始transcoding转码中done完成failed失败
-duration	Long	时长（毫秒），只有video才有
-detail	JSON	媒体描述信息，分辨率
--width	Integer	宽
--height	Integer	长
-mediaUrl	String	媒体片段url
-coverImg	String	封面图
-optimalFramePosition	Long	最优帧位置（毫秒），最优帧在片段中的位置

获取模板协议

path：/vlog/open/template/list

version：1.0.0

入参

参数名称	类型	是否必填	参数说明
userId	String	是	用户id
caseId	String	是	景区id
productId	String	是	作品id

出参

字段名	类型	备注
code	String	异常码
message	String	异常原因
localizedMsg	String
data	JSON
-templateId	String	模版id
-templateVersion	String	模版版本
-canRecompose	boolean	能否重复合成
-templateLens	List
--key	String	镜头id（在镜头中位置）
--duration	Long	时长
--bestFrame	Boolean	是否在视频结果做过度特效
--type	String	类型

自定义片段合成作品

path：/vlog/open/recompose

version：1.0.0

入参

参数名称	类型	是否必填	参数说明
userId	String	是	用户id
caseId	String	是	景区id
productId	String	是	作品id
fragments	List	是	自定义合成作品的视频片段列表，需要和模板需要的人脸数量对齐
-momentId	String	是	精彩瞬间id
-timePointStart	Long	是	开始时间，默认为最优帧，毫秒
-duration	Long	是	时长，毫秒
-key	String	是	镜头id

出参

字段名	类型	备注
code	String	异常码
message	String	异常原因
localizedMsg	String
data	String	jobId，任务id