长视频库

最近更新时间：2023.06.16 16:16:30

首次发布时间：2021.09.08 11:03:53

长视频库是内容定制提供的一项扩展能力，能够将客户的长视频媒资库与内容定制丰富的横版短视频/竖版小视频资源进行关联，该能力目前可以在商品推广的场景下使用。
基于长视频库 OpenAPI，客户可以灵活的实现长视频库的同步和管理，打通客户系统和内容定制的长视频库。长视频库 OpenAPI 不建议直接在在线服务场景 (例如推荐) 中使用，同账号下单个接口限流100QPS，批量操作默认上限30个。
长视频库 OpenAPI 包括以下接口：

【创建/更新长视频】：提供长视频库的批量创建/更新能力
【批量获取长视频】：提供长视频库的批量获取能力
【删除长视频】：提供长视频库的批量删除能力
【获取长视频列表】：提供长视频库的列表获取能力

名词解释

ExternalId：用户侧的长视频Id，用于系统打通。规范：不允许为空，渠道下唯一，大小写敏感，仅支持大小写英文、数字组合而成，长度上限为20个字符。

接口说明

公共部分

请求

请求url

请求url由3部分组成

KEY	VALUE/说明
Host（固定值）	https://mercury.volcengineapi.com
Action	按实际Action填写，下文会写明
Version（固定值）	2022-01-01

例如：https://mercury.volcengineapi.com?Action=UpsertLongVideos&Version=2022-01-01

请求header

KEY	VALUE/说明
Content-Type（固定值）	application/json
ServiceName（固定值）	volc_torchlight_api
AccessKey	按实际ak填写
SecretKey	按实际sk填写

验签及请求公共参数逻辑参考火山引擎官网：

火山引擎签名机制
开通账号权限后，可获取AccessKey进行验签，详情请参见：https://www.volcengine.com/docs/6291/65568

响应

ResponseMetadata

字段名	字段类型	是否必填	说明
RequestId	string	是	请求链路Id
Action	string	是	访问Action
Version	string	是	API版本号
Service	string	是	访问的服务名称
Region	string	是	访问区域
Error	Error	否	错误信息

创建/更新长视频 - UpsertLongVideos

请求url

https://mercury.volcengineapi.com?Action=UpsertLongVideos&Version=2022-01-01

请求method

Post

数据入参

字段名	字段类型	是否必填	说明
UtmSource	string	是	渠道号
LongVideos	[]UpsertLongVideo	是	长视频列表，支持批量请求，单次最多30条，长视频库当前最多支持50000条记录

数据出参

字段名	字段类型	是否必填	说明
ResponseMetadata	ResponseMetadata	是	通用返回
Result	UpsertLongVideosResult	是	基本请求结果

调用示例

携带公共参数验签，POST请求接口同步内容基本信息（公共参数验签参见上文）

{
    "UtmSource": "test_utm_default_content",
    "LongVideos": [
        {
            "ExternalId": "l00000000001",
            "Name": "勇敢的心",
            "Directors": [
                "梅尔·吉布森"
            ],
            "Actors": [
                "梅尔·吉布森",
                "苏菲·玛索",
                "布莱恩·考克斯"
            ],
            "Extra": ""
        },
        {
            "ExternalId": "l00000000002",
            "Name": "大白鲨",
            "Directors": [
                "史蒂文·斯皮尔伯格"
            ],
            "Actors": [
                "罗伊·谢德",
                "罗伯特·肖",
                "理查德·德莱福斯"
            ],
            "Extra": ""
        }
    ]
}

返回示例

正常返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230306141608B849389B566D982F7762",
        "Action": "UpsertLongVideos",
        "Version": "2022-01-01",
        "Service": "volc_torchlight_api",
        "Region": "cn-north-1"
    },
    "Result": {
        "UpsertFailLongVideos": []
    }
}

错误返回示例

{
    "ResponseMetadata": {
        "RequestId": "202210271151020102121450321B8D2A21",
        "Action": "UpsertLongVideos",
        "Version": "2022-01-01",
        "Service": "volc_torchlight_api",
        "Region": "cn-north-1",
        "Error": {
            "CodeN": 100010,
            "Code": "SignatureDoesNotMatch",
            "Message": "..."
        }
    }
}

批量获取长视频 - MGetLongVideos

请求url

https://mercury.volcengineapi.com?Action=MGetLongVideos&Version=2022-01-01

请求method

Post

数据入参

字段名	字段类型	是否必填	说明
UtmSource	string	是	渠道号
ExternalIds	[]string	是	要查询的视频Id列表，批量一次最多30个

数据出参

字段名	字段类型	是否必填	说明
ResponseMetadata	ResponseMetadata	是	通用返回
LongVideos	[]LongVideo	是	查到的长视频列表

调用示例

携带公共参数验签，POST请求接口同步内容基本信息（公共参数验签参见上文）

{
    "UtmSource": "test_utm_default_content",
    "ExternalIds": [
        "l00000000001",
        "l00000000002"
    ]
}

返回示例

正常返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230306141442F547EA86128A572E6499",
        "Action": "MGetLongVideos",
        "Version": "2022-01-01",
        "Service": "volc_torchlight_api",
        "Region": "cn-north-1"
    },
    "Result": {
        "LongVideos": [
            {
                "ExternalId": "l00000000001",
                "Name": "勇敢的心",
                "MatchedName": "勇敢的心",
                "Directors": [
                    "梅尔·吉布森"
                ],
                "Actors": [
                    "梅尔·吉布森",
                    "苏菲·玛索",
                    "布莱恩·考克斯"
                ],
                "Extra": ""
            },
            {
                "ExternalId": "l00000000002",
                "Name": "大白鲨",
                "MatchedName": "大白鲨",
                "Directors": [
                    "史蒂文·斯皮尔伯格"
                ],
                "Actors": [
                    "罗伊·谢德",
                    "罗伯特·肖",
                    "理查德·德莱福斯"
                ],
                "Extra": ""
            }
        ]
    }
}

错误返回示例

{
    "ResponseMetadata": {
        "RequestId": "202210271151020102121450321B8D2A21",
        "Action": "DeleteLongVideos",
        "Version": "2022-01-01",
        "Service": "volc_torchlight_api",
        "Region": "cn-north-1",
        "Error": {
            "CodeN": 100010,
            "Code": "SignatureDoesNotMatch",
            "Message": "..."
        }
    }
}

删除长视频 - DeleteLongVideos

请求url

https://mercury.volcengineapi.com?Action=MGetLongVideos&Version=2022-01-01

请求method

Post

数据入参

字段名	字段类型	是否必填	说明
UtmSource	string	是	渠道号
ExternalIds	[]string	是	要删除的视频ExternalId列表，一次最多30个

数据出参

字段名	字段类型	是否必填	说明
ResponseMetadata	ResponseMetadata	是	通用返回

调用示例

携带公共参数验签，POST请求接口同步内容基本信息（公共参数验签参见上文）

{
    "UtmSource":"test_utm_default_content",
    "ExternalIds":["l00000000002"]
}

返回示例

正常返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230306141554DD9F80E9FF7DE12F5C82",
        "Action": "DeleteLongVideos",
        "Version": "2022-01-01",
        "Service": "volc_torchlight_api",
        "Region": "cn-north-1"
    },
    "Result": {}
}

错误返回示例

{
    "ResponseMetadata": {
        "RequestId": "202210271151020102121450321B8D2A21",
        "Action": "DeleteLongVideos",
        "Version": "2022-01-01",
        "Service": "volc_torchlight_api",
        "Region": "cn-north-1",
        "Error": {
            "CodeN": 100010,
            "Code": "SignatureDoesNotMatch",
            "Message": "..."
        }
    }
}

获取长视频列表 - ListLongVideos

长视频列表按用户分配 ExternalId 字典序排序，暂不支持自定义排序

请求url

https://mercury.volcengineapi.com?Action=ListLongVideos&Version=2022-01-01

请求method

Post

数据入参

字段名	字段类型	是否必填	说明
UtmSource	string	是	渠道号
PageNumber	number	否	翻页页码，整数，起始值为1，默认值为1；
PageSize	number	否	翻页每页的大小，整数，默认值为10，最大值为100

数据出参

字段名	字段类型	是否必填	说明
PageNumber	number	是	原样返回请求参数（请求参数未填写时则为参数默认值）
PageSize	number	是	原样返回请求参数值（请求参数未填写时则为参数默认值）
TotalCount	number	是	查询结果的总数
LongVideos	[]LongVideo	是	长视频信息列表

调用示例

携带公共参数验签，POST请求接口同步内容基本信息（公共参数验签参见上文）

{
    "UtmSource":"test_utm_default_content",
    "PageSize":3,
    "PageNumber":1
}

返回示例

正常返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230306141941A2259D4C07737D2E777B",
        "Action": "ListLongVideos",
        "Version": "2022-01-01",
        "Service": "volc_torchlight_api",
        "Region": "cn-north-1"
    },
    "Result": {
        "PageNumber": 1,
        "PageSize": 3,
        "TotalCount": 2,
        "LongVideos": [
            {
                "ExternalId": "l00000000001",
                "Name": "勇敢的心",
                "MatchedName": "勇敢的心",
                "Directors": [
                    "梅尔·吉布森"
                ],
                "Actors": [
                    "梅尔·吉布森",
                    "苏菲·玛索",
                    "布莱恩·考克斯"
                ],
                "Extra": ""
            },
            {
                "ExternalId": "l00000000002",
                "Name": "大白鲨",
                "MatchedName": "大白鲨",
                "Directors": [
                    "史蒂文·斯皮尔伯格"
                ],
                "Actors": [
                    "罗伊·谢德",
                    "罗伯特·肖",
                    "理查德·德莱福斯"
                ],
                "Extra": ""
            }
        ]
    }
}

错误返回示例

{
    "ResponseMetadata": {
        "RequestId": "202210271151020102121450321B8D2A21",
        "Action": "ListLongVideos",
        "Version": "2022-01-01",
        "Service": "volc_torchlight_api",
        "Region": "cn-north-1",
        "Error": {
            "CodeN": 100010,
            "Code": "SignatureDoesNotMatch",
            "Message": "..."
        }
    }
}