全部产品

阿里云Vlog开放API

更新时间

服务版本号

说明

备注

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下全量合成的成品列表

1、服务介

1.1 产品简介

阿里云Vlog:以游客为中心,提供含智能采集,智能生产,智能分发的一站式解决方案,可实现在在采集点拍摄后,自动生成“人+景”的Vlog短视频。

1.2 产品组成

Vlog产品组成

阿里云Vlog包含三大核心基础设施:

1)智能采集,拍摄游客最美瞬间,解锁旅程中的“高光”时刻,提升分享意愿。

2)智能生产,汇集片段优选、自动生产、视觉特效等AI能力的一体机,实现秒级生成。

3)智能分发,通过“取Vlog机”一键下载短视频,抓住用户分享的黄金瞬间。

1.3 服务说明

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

2、接口说明

2.1 服务开通及秘钥获取

本服务需完成以下前置准备:

1)准备一个认证完成的阿里云账号,如果没有阿里云账号,可访问链接进行注册。

2)登陆数字商业引擎平台,按照流程填写信息并申请入驻,审批通过后进行下一步操作。

3)创建景区实例,作为景区之间的隔离维度,比如一个景区创建一个实例,一个数字商业引擎可管理多个实例。

第一步:填写景区信息。创建项目

第二步:添加“阿里云Vlog”服务。添加能力

4)能力开通后即可按照步骤激活部署阿里云Vlog基础设施。

激活流程

5)基础设施激活后,可通过实例总览页右方的秘钥调用本服务。

秘钥

2.2 接入方式

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"));

2.3 接口调用流程说明

本服务共包含5个接口,请按照以下流程进行业务流程编写和调用,5个接口需全部对接完成才可以完成业务最小闭环。

实际调用前,请务必保证现场已经有Vlog基础设施布置。

接口调用流程

2.4 接口说明

1)注册用户

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

2) 查询景区列表

path:/vlog/open/case/list

version:1.1.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

景区展示宣传视频

3)查询景区详情

path:/vlog/open/case/detail

version:1.0.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

视频时长

4)生成vlog

2021年4月14日后,支持返回最优帧美颜图片,版本号变更成1.1.0版本。

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

5)查询vlog生成情况

path:/vlog/open/status/query

version:1.2.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

摄像头名称

6)查询美颜照片生成进度

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

最优帧图片地址

7)获取足迹列表

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

摄像头名称

8)埋点服务

path:/vlog/open/data/backflow

version:1.0.0

入参

参数名称

类型

是否必填

参数说明

userId

String

终端用户id

action

String

详见“action列表”

time

Date

最晚日期,默认值为当前日期

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_PAID

为vlog付费时使用(支付成功进行该数据埋点)

出参

字段名

类型

备注

id

String

request id

code

Integer

错误码,成功时返回200

message

String

错误描述,成功时返回"success"

localizedMsg

String

本地语言错误消息

9)订单列表查询(仅在使用“一录打卡”小程序并开通支付功能场景下使用)

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 订单等待支付中

2.5 二次编辑服务

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

1)查询作品精彩片段列表

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

最优帧位置(毫秒),最优帧在片段中的位置

2)获取模板协议

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

类型

3)自定义片段合成作品

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