短视频模版内容开放服务商对接方案

更新时间：2023/08/28 访问次数：1673

一、名词解释
二、整体对接方案
三、内容开放核心能力
四、对接具体流程步骤
五、开放平台其他文档引导

一、名词解释

名词	解释	更多
appkey	ISV入驻开放平台后，申请的一个应用身份key
open_id	淘宝加密后的用户身份ID（用于替换nick，由于安全策略，nick不在建议外部使用），同一个淘宝用户不同appkey加密后值不同，appkey下唯一；code换token后接口会返回此id
callback url	创建应用时输入的回调地址，此地址用于接受平台授权时的code，同时回调地址在完成授权后需要具备浏览器打开三方工具产品页面能力	示例： www.fuwushang123.com/callback
外部编码	服务商在发布短视频模版时，需要输入一个外部编码，用于维护平台视频模版和三方工具内视频脚本源文件的一一映射关系，appkey下外部编码唯一，不可重复
授权code	oauth授权概念，用户同一授权后，生成授权code，isv系统接到code请求后执行换token流程	平台请求示例：www.fuwushang123.com/callback?code=xxxx&state=外部编码。
授权token	oauth授权概念，通过code换取，只有换取了token后，才真正意义上完成了用户和应用的授权

二、整体对接方案

1.ISV视频模版发布

2.商家发现模版和使用

说明：上图中三方工具的打开链接仅做说明使用，实际链接为appkey配置的回调地址+code和state参数，state参数这里作为外部编码使用，可以根据此参数获取商家要使用的目标模版。如果您的应用回调地址为www.xxx.com/callback，视频模版在平台录入的外部编码为123，则实际打开的地址为www.xxx.com/callback?code=xxx&state=123。

3.用户登陆信息识别和视频交付流程

4.三方工具内登陆态过期处理

说明：从千牛首次跳转三方工具后，用户停留三方工具做视频剪辑，三方工具可以识别和自行维护用户的登录态信息。若三方设置的登陆态有效期过期后，可以走授权流程重新获取token和用户信息，注意state上携带好视频模版的外部编码，用于授权后的目标视频文件打开。

具体一次登陆态的有效时长，可以按需自行设置，比如12小时、24小时等。

三、内容开放核心能力

1. 接口能力

api调用文档参考 API调用方法详解。

1）接口列表

接口	类型	是否需要商家授权	功能	公开文档
taobao.content.video.service.list	TOPAPI	否	已经发布的视频模版列表查询	https://open.taobao.com/api.htm?docId=65659&docType=2
taobao.picture.upload	TOPAPI	是	上传单张图片	https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=140
taobao.picture.get	TOPAPI	是	获取图片信息	https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=138
taobao.content.media.upload.secret	TOPAPI	是	获取oss上传的许可secret	https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=66575
taobao.content.media.upload.pub	TOPAPI	是	同步文件到淘宝多媒体平台	https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=66574
taobao.content.media.upload.get	TOPAPI	是	查询文件上传多媒体平台的进度结果	https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=66573
taobao.content.video.publish	TOPAPI	是	发布文件到商家视频空间	https://open.taobao.com/api.htm?docId=65631&docType=2
taobao.content.video.info.get	TOPAPI	是	视频空间视频基础信息查询	https://open.taobao.com/api.htm?docId=65632&docType=2
taobao.content.confirm.url.get	TOPAPI	是	获取视频模版下单确认页链接	https://open.taobao.com/api.htm?docId=65667&docType=2
alibaba.item.edit.schema.get	TOPAPI	是	获取商品信息scheme	https://open.taobao.com/v2/doc?#/apiFile?docType=2&docId=53967
alibaba.item.edit.fastupdate	TOPAPI	是	商品信息部分更新(主图)	https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=54542

2）其他接口文档说明

1、淘宝视频/图片上传

相关api涉及视频文件fileId, 涉及封面图片url均需为淘宝商家空间的文件资源。

若需使用视频文件, 则需发布视频文件到商家视频空间, 获取淘宝文件fileId；

若需使用图片资源, 则需为商家图片空间的图片url, 或者把本地图片上传到商家图片空间, 获取淘宝图片url。

① 图片上传

上传单张图片 taobao.picture.upload；

获取图片信息 taobao.picture.get。

② 视频上传（新）

获取到的视频fileId可用于发布视频空间/关注(订阅)。

i）获取oss上传的许可secret / taobao.content.media.upload.secret

获取oss上传的许可secret等, 作为第2步文件上传的入参。

{
  "result": {
    "accessKeyId": "STS.NU7KbxxxxxxMsLsFefYRm",
    "accessKeySecret": "EZ1x3emZAtjPa3SNxxxxxxxxx2AEugkj3BHbg5c",
    "expiration": "2023-04-20T10:18:28Z",
    "securityToken": "CAIS2AJ1q6Ft5BxxxxxxxxxcOkTjlXMZf8lJiZz5jzz2IHFLeHFvB+0dsPsymG5Q6/oYlrVvTIcATkvCccZ28tFM/Bi6Yo3H/pfutOZa2Mf8QdUk04dqhJ28Wf7waf+AUAjECTmd5NYao9bTcTGlQCbqU/mggoJmadI6RxSxaSE8av5dOgplrr19Vx7WLu3/CgP2pWDSAUF0wD0e71ly8qOi2MaRxwPDhVnhsI8vqp/2P4KvYrtHXuB2WMzn2/dtJOiTknxM7AAP/6BwkKFC5XLAuNWcBVQWgV2POPGG9cZ0fk0rJPomHLYBp//6ifB+pqnUkYD2zRsKf8MtCnuFFdn/m5eeQrjxZ45iL4yWYSqdjoq9UbDuqB4hbH4hMwdHRsEsMHcYC2Z3G26GcvD5pQuUPVr/FfDYjPsstoZy1xDj+tyWKl6TBrKCyjbYryqoz77JXBqAAV0k2TM9HxPFX54Tcg8JcyL5MejlNgp9aay0RWStZdTG6V1z5gykrRBCvNITkaTRShZrHTtcR3bwCYCtcEbvheoDM6fsSXI5HB6aHEVIiNU/V/VnnlRD3OynTxwdFnyYTlyCS5WRVl0IUVplU8U3Ir3tOmh18K8L+ybXLp2OJxvW"
  },
  "success": true
}

ii）上传视频到oss

注意：文件大小不要超过500MB。

oss sdk下载 https://help.aliyun.com/document_detail/456362.html

<dependency>
  <groupId>com.aliyun.oss</groupId>
  <artifactId>aliyun-sdk-oss</artifactId>
  <version>3.10.2</version>
</dependency>

java 案例代码

package ali;
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.serializer.SerializerFeature;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.model.PutObjectRequest;
import com.aliyun.oss.model.PutObjectResult;
import java.io.File;
import java.util.UUID;
public class IsvUpload {
    public static void main(String[] args) {
        // Endpoint以杭州为例，其它Region请按实际情况填写, 详见阿里云oss endpoint选择推荐。
        String endpoint = "oss-cn-zhangjiakou.aliyuncs.com";
        // 填写获取的临时访问密钥AccessKey ID和AccessKey Secret，非阿里云账号AccessKey ID和AccessKey Secret。
        String accessKeyId = "STS.NU7KbxxxxxxxxYRm";
        String accessKeySecret = "EZ1x3emZAtjPaxxxxxvBmrgH2AEugkj3BHbg5c";
        // 填写步骤五获取的安全令牌SecurityToken。
        String securityToken = "CAIS2AJ1q6xxxxxx51I9qj6TcOkTjlXMZf8lJiZz5jzz2IHFLeHFvB+0dsPsymG5Q6/oYlrVvTIcATkvCccZ28tFM/Bi6Yo3H/pfutOZa2Mf8QdUk04dqhJ28Wf7waf+AUAjECTmd5NYao9bTcTGlQCbqU/mggoJmadI6RxSxaSE8av5dOgplrr19Vx7WLu3/CgP2pWDSAUF0wD0e71ly8qOi2MaRxwPDhVnhsI8vqp/2P4KvYrtHXuB2WMzn2/dtJOiTknxM7AAP/6BwkKFC5XLAuNWcBVQWgV2POPGG9cZ0fk0rJPomHLYBp//6ifB+pqnUkYD2zRsKf8MtCnuFFdn/m5eeQrjxZ45iL4yWYSqdjoq9UbDuqB4hbH4hMwdHRsEsMHcYC2Z3G26GcvD5pQuUPVr/FfDYjPsstoZy1xDj+tyWKl6TBrKCyjbYryqoz77JXBqAAV0k2TM9HxPFX54Tcg8JcyL5MejlNgp9aay0RWStZdTG6V1z5gykrRBCvNITkaTRShZrHTtcR3bwCYCtcEbvheoDM6fsSXI5HB6aHEVIiNU/V/VnnlRD3OynTxwdFnyYTlyCS5WRVl0IUVplU8U3Ir3tOmh18K8L+ybXLp2OJxvW";
        // 创建OSSClient实例。
        OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, securityToken);
        String bucket = "top-content-online" ;//这里使用secret接口返回的bucket即可
        String appKey = Env.appkey;
        // 生成一个唯一文件id 需本地存储改id!!!! 作为后续api入参使用
        String uuid_file_name = UUID.randomUUID()+".mp4";
        // 这里规则固定，必须制定到 media-{appKey}这个oss目录，同时文件名要用UUID随机生成
        String file = "media-"+appKey+"/"+ uuid_file_name;
        // 本地待上传的文件
        File localFile = new File("/Users/chengfei/Pictures/1mv-3-4.mp4");
        PutObjectRequest putObjectRequest = new PutObjectRequest(bucket, file, localFile);
        // 上传文件。
        PutObjectResult putObjectResult = ossClient.putObject(putObjectRequest);
        System.out.println("uuid_file_name: " + uuid_file_name);
        System.out.println("oss_path: " + file);
        System.out.println("oss_res: ");
        System.out.println(JSON.toJSONString(putObjectResult, SerializerFeature.PrettyFormat));
        // 关闭OSSClient。
        ossClient.shutdown();
    }
}

上传结果，关注并记录 uuid_file_name 字段, 需后续使用。

uuid_file_name: 3b92f23d-57xxxxx263-f34380a1b344.mp4
oss_path: media-33126821/3b92f23d-575xxx1-b263-f34380a1b344.mp4
oss_res: 
{
    "clientCRC":291131900001063,
    "eTag":"1333455053BExxxAA2E7D1BC118936",
    "requestId":"644103xxxE4336315CE89D",
    "serverCRC":291130003881063
}

iii）同步文件到淘宝多媒体平台 / taobao.content.media.upload.pub

这里的appkey需要跟上传视频oss的时候的appkey一致。

注意biz_code 取决于目标业务场景。

该视频文件，

若要用于发布关注(订阅), 则需填入关注的业务编码(out_tao_dingyue)；

若要用于发布视频空间, 则需填入视频空间的业务编码(out_tao_mv)。

这里的 upload_token 用于下一步操作。

{
  "content_media_upload_pub_response": {
    "pub_oss_file_to_multi_media_response": {
      "upload_token": "M-d98xxxx85-47f6-b4f1-2573a0106af5"
    }
  }
}

iv）查询文件同步多媒体平台的进度结果 / taobao.content.media.upload.get

这里的appkey需要跟上传视频oss的时候的appkey一致，一段时间后（约1~10秒）会同步完成，这里 file_id 用于下一步操作。

当同步完成后获取到 file_id 如下
{
  "done": true,
  "file_id": "0188-aef33c61-a1ab32c3-8847ca27-7b7f",
  "mime_type": "video/mp4"
}

③ 视频推送到视频空间

i）视频发布到视频空间

appkey类型	调用接口	说明
短视频工具	taobao.content.video.publishx	不限制次数调用，详见短视频工具对接说明。

说明：此时获取返回的 id 别名(内容id contentId 视频id) 。

注意：视频封面图片必须是商家图片空间中的图片。存在部分商品的相关图片本身就非商家的图片, 可试用图片接口重新上传一次后使用。

商家可在视频空间查看, 视频空间审核状态、预览、管理等。

https://myseller.taobao.com/home.htm/sucai-video/home

ii）获取视频信息 taobao.content.video.info.get

使用内容id 调用视频信息查询接口，获取包括播放链接在内的视频元数据信息。

iii）查询视频空间列表 taobao.content.video.info.list

2、商品部分信息(主图)更新说明

先获取商品部分信息scheme alibaba.item.edit.schema.get

入参:

fields/过滤字段: video,images,imageVideo

会获取到scheme如:

追加或替换字段(商品主视频id)值：

为上传到视频空间后拿到的视频文件id：

然后作为参数，调用 api alibaba.item.edit.fastupdate 即可更新；

之后去商品信息编辑页, 商品售卖展示页, 即可看到效果。

2. 消息能力

消息列表

topic	类型	是否需要授权	功能	公开文档
taobao_content_OrderPaid	广播	是	商家购买视频模版支付完成时发送	taobao_content_OrderPaid

四、对接具体流程步骤

1.入驻平台开发者身份

请参考文档应用软件开发商-接入指南。

2.创建应用，获取appkey和权限包（以下为示意图，以最终实际入驻为准）

应用创建地址点击此处跳转访问。

3.软件开发，完成系列消息和API能力对接，对接完成后将appkey上线

① 获取平台开发版SDK；

② 使用SDK发起联调地址的调用（地址：http://pre-gw.api.taobao.com/top/router/rest ，应用上线前替换为正式地址）。

//在api上线前，处于联调阶段，
TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
ContentVideoServiceListRequest req = new ContentVideoServiceListRequest();
req.setStatus(1L);
req.setPageNo(1L);
req.setPageSize(1L);
req.setVideoServiceId(1L);
ContentVideoServiceListResponse rsp = client.execute(req);
System.out.println(rsp.getBody());

4.发布视频模版

一个appkey可以发布并关联多个短视频模板, 下面是单个短视频模板创建流程。

如果下拉选单中找不到所需的剪辑工具，请联系运营审核。

这里截图参数没有截全, 关注一下: 这里可以上传视频文件(短视频模板)。

走完审核流程后, 该短视频模板即可在千牛菜单上对商家可见, 商家即可选购短视频模板, 进行使用和购买。

五、开放平台其他文档引导

入驻成为生态伙伴，接入指南参考	应用软件开发商-接入指南
API调用对接	API调用方法详解
授权体系对接	用户授权介绍
平台技术文档	新手指南

FAQ

关于此文档暂时还没有FAQ

有用(0) 我要提问

开放平台

内容创作工具-业务介绍