菜单

素材库API

一、获取素材详情

1、v2接口说明

（1）原v1接口已不再维护，请切换至v2接口请求数据，v2接口升级如下：

变更部分字段名，如标签改为tag字段

（2）更新频率：素材信息与XMP素材库同步更新

（3）操作权限为公司管理员，仅支持查询企业素材库的素材信息

（4）QPM限频为120，一分钟内请求超过120次会返回“请求太频繁”，需要等下一分钟才能再请求

2、接口路径

POST https://xmp-open.mobvista.com/v2/media/material/list

3、请求参数

公共请求参数：请参考接口请求协议

•Body

除 is_deleted、page、page_size 外的字段必须至少传一个

参数	类型	必填	说明
start_date	string	N	创建开始日期（素材创建时间）YYYY-MM-DD，创建开始日期不能晚于创建结束日期，最长跨度不超过30天
end_date	string	N	创建结束日期（素材创建时间）YYYY-MM-DD ，必须与创建开始日期一起传
start_date_up	string	N	更新开始日期（素材更新时间）YYYY-MM-DD，更新开始日期不能晚于更新结束日期，最长跨度不超过30天
end_date_up	string	N	更新结束日期（素材更新时间）YYYY-MM-DD ，必须与更新开始日期一起传
user_material_id	array	N	素材local id
md5_file_id	array	N	素材md5
is_deleted	int	N	是否删除，不传则返回全部素材，0表示未删除，1表示已删除
folder_id	array	N	文件夹id
page	int	N	当前页数，默认1
page_size	int	N	每页数量，默认200，可选1至1000

4、请求示例

{
  "client_id": "xxx",
  "timestamp": 1608776690,
  "sign": "05d481dc241a7a1daa5b2a7fa2b51dc5",
  "start_date":"2021-09-01", 
  "end_date":"2021-09-30",   
  "user_material_id":["81547","81546"],    
  "md5_file_id":["9ce6c0666045c02b839dce4d36951375","9ce6c0666045c02b839dce4d36951378"],
  "is_deleted":0, # 除is_deleted、page、page_size外，其它字段至少传一个
  "folder_id": [1111,22222],
  "page":2,
  "page_size":200
}

5、返回参数

参数	类型	说明
code	int	错误码
msg	string	消息
data	array	返回的接口内容
data.material_name	string	素材名称
data.material_id	int	素材id
data.user_material_id	int	素材local id
data.md5_file_id	string	素材md5
data.material_type	string	素材类型（image，video，other）
data.tag	array	标签
data.designer	array	设计师
data.customer	array	创意人员
data.width	int	宽
data.height	int	高
data.shape	string	形状（横版、竖版、方形）
data.format	string	格式
data.duration	float	时长，单位为秒（图片返回0）
data.bit_rate	float	视频码率，单位为bps（图片返回0）
data.url	string	缩略图地址
data.file_url	string	文件地址
data.size	string	文件大小
data.is_deleted	int	0表示未删除，1表示已删除
data.folder_id	int	文件夹id，操作权限对应公司管理员
data.folder_name	string	文件夹名称
data.audit_status	int	审核状态，0表示待审核，1表示审核通过，-1表示不过审。文件夹未开启审核时，返回-2
data.created_time	datetime	素材创建时间
data.updated_time	datetime	素材更新时间

6、返回示例

{
	"code": 0,
	"msg": "success",
	"data": [
		{
			"user_material_id": 1,
			"material_name": "测试(2).mp4",
			"material_id": 1,
			"md5_file_id": "e6148d3406faa0f2cedf8eb623e09892",
			"material_type": "video",
			"tag": [
				{
					"level": 2,
					"parent_id": 1,
					"id": 1,
					"name": "奇魔猪1"
				},
				{
					"level": 2,
					"parent_id": 1,
					"id": 1,
					"name": "mp_222"
				}
			],
			"designer": [
				{
					"id": 1,
					"name": "1"
				}
			],
			"customer": [
				{
					"id": 27,
					"name": "1"
				}
			],
			"width": 1280,
			"height": 720,
			"shape": "横版",
			"format": "mp4",
			"duration": 18.92,
			"bit_rate": 8184636,
			"url": "https://xmp-material-cns.mobvista.com/video_cover_multi/e6148d3406faa0f2cedf8eb623e09892/23a685c3e86f6c1d13dc121f47cfd0ff.jpg",
			"file_url": "https://xmp-material-cns.mobvista.com/video/e6/e6148d3406faa0f2cedf8eb623e09892.mp4",
			"size": "18.46 MB",
			"is_deleted": 0,
			"folder_id": 1,
			"folder_name": "上传测试",
			"audit_status": 1,
			"created_time": "2023-12-29 16:52:36",
			"updated_time": "2023-12-29 16:52:36"
		}
	]
}

二、上传素材

1、接口说明

（1）单次请求最多上传10个素材

（2）操作权限为公司管理员

（3）QPM限频为120，一分钟内请求超过120次会返回“请求太频繁”，需要等下一分钟才能再请求

2、接口路径

POST https://xmp-open.mobvista.com/v1/media/material/upload

3、请求参数

公共请求参数：请参考接口请求协议

•Body

参数	类型	必填	说明
data	array	Y	data包含所有要上传素材的对象
data.folder_id	int	Y	文件夹id
data.user_material_name	string	Y	素材名称，限200个字符。同一文件夹内素材名称不可重复
data.client_custom_id	string	N	客户自有素材id
data.material_url	string	Y	素材文件地址，支持传OSS/S3地址等可公网访问的地址。素材文件名含有中文时需进行urlencode
data.material_ext	string	Y	素材后缀。图片：jpg、jpeg、png、bmp；视频：mp4、mov、avi、mpeg；试玩：html、htm、zip
data.material_type	int	Y	素材类型。1为图片，2为视频，10为试玩
data.media	string	N	渠道，当素材类型=10时必填，可传：mintegral、applovin、unity、ironsource，只能传一个
data.tag_id	array	N	标签id
data.customer_id	[]int	N	创意人，默认值为空。可传多个，传公司下任一用户id（启用状态）
data.designer_id	[]int	N	设计师，默认值为空。可传多个，必须设计部门下的用户id（启用状态）
data.audit_status	int	N	审核状态，默认为审核通过，0：待审核，1：审核通过，-1：不过审。仅当素材库开启审核时有效
data.sync_mode	string	N	async表示异步，适用于大文件上传，返回参数不会有user_material_id；sync或空表示同步，返回参数有user_material_id
data.file_sign	string	N	源文件md5校验，可空。当有值时，会对下载的url文件进行校验。校验成功后才会入库。
data.filter_duplicate	Boolean	N	过滤重复素材，默认false。当为true表示，如果当前文件夹存在相同md5的素材时，则直接返回成功。允许名称不一致；如果为false，则允许重复上传，名称相同时会自动增加数字后缀。
data.client_custom_id	string	N	客户自有素材id

4、请求示例

{
     "client_id": "xxxx",
     "timestamp": 1608776690,
     "sign": "05d481dc241a7a1daa5b2a7fa2b51dc5",
     "data": [
         {
             "material_type": 1,
             "material_url": "https://xxx.com/image/5d/sc_upload.png",
             "user_material_name": "sc_upload.png",
             "material_ext": "png", 
             "folder_id": 12345,
             "designer_id": [
                111,222
             ],
             "customer_id": [
                 333
             ]
         }
     ]
 }

5、返回参数

参数	类型	说明
code	int	错误码
msg	string	消息
data	array	返回的接口内容
data.folder_id	int	文件夹id
data.user_material_id	int	xmp内部的素材id，具有唯一性。上传失败时该字段为0
data.material_id	int	素材id
data.md5_file_id	string	素材md5
data.user_material_name	string	xmp素材名称
data.client_custom_id	string	客户自有素材id
data.status	int	状态，0为失败，1为成功
data.error_msg	string	错误信息

6、返回示例

{
	"code": 0,
	"msg": "success",
	"data": [
		{
			"client_custom_id": "test_123",
			"folder_id": 1,
			"user_material_id": 1,
			"user_material_name": "1",
			"material_id": 1,
			"md5_file_id": "abc",
			"status": 1,
			"error_msg": ""
		}
	]
}

三、修改素材属性

1、接口说明

（1）单次请求最多修改10个素材

（2）操作权限为公司管理员

（3）QPM限频为120，一分钟内请求超过120次会返回“请求太频繁”，需要等下一分钟才能再请求

2、接口路径

POST https://xmp-open.mobvista.com/v1/media/material/update

3、请求参数

公共请求参数：请参考接口请求协议

•Body

参数	类型	必填	说明
data	array	–	data包含所有对象
data.user_material_id	int	Y	素材local id
data.key	array	Y	需要把待修改的字段全部传入，否则不会执行相应处理：user_material_name、tag_id、designer_id、customer_id、audit_status、remark、is_deleted
data.user_material_name	int	N	素材名称
data.type	string	N	修改方式，同时应用于标签、设计师和创意人的修改追加：append，覆盖：override 若不传默认为覆盖
data.tag_id	array	N	标签id
data.designer_id	array	N	设计师用户id
data.customer_id	array	N	创意人用户id
data.audit_status	int	N	审核状态，0：待审核，1：审核通过，-1：审核不通过
data.remark	string	N	素材备注，限200个字符
data.is_deleted	int	N	是否删除素材，1：删除，其他值：忽略不处理

4、请求示例

{
    "client_id": "xmp",
    "timestamp": {{time_now}},
    "sign": "{{sign}}",
    "data": [
        {
            "user_material_id": 3510287,
            "key": [
                "user_material_name",
                "designer_id"
            ],
            "user_material_name": "",
            "type": "append",
            "designer_id": [
                1,
                2,
                3
            ]
        }
    ]
}

5、返回参数

参数	类型	说明
code	int	错误码
msg	string	消息
data	array	返回的接口内容
data.user_material_id	int	素材local id
data.status	int	状态，0为不成功，1为成功
data.error_msg	string	错误信息

6、返回示例

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "user_material_id": 3510287,
            "status": 1,
            "error_msg": ""
        }
    ]
}

四、获取素材文件夹列表

1、接口说明

（1）返回素材库的文件夹列表

（2）操作权限为公司管理员

（3）QPM限频为120，一分钟内请求超过120次会返回“请求太频繁”，需要等下一分钟才能再请求

（4）该接口会返回父级本身及父级以下全部子文件夹信息

2、接口路径

POST https://xmp-open.mobvista.com/v1/media/folder/list

3、请求参数

公共请求参数：请参考接口请求协议

•Body

参数	类型	必填	说明
folder_type	int	Y	文件夹类型，1为我的素材库，2为企业素材库
parent_folder_id	[]int	N	父级文件夹ID
user_id	int	N	1、返回包含该用户或者该用户所在部门的素材文件夹 2、不传按公司管理员权限处理

4、请求示例

{
     "client_id": "xxxx",
     "timestamp": 1608776690,
     "sign": "05d481dc241a7a1daa5b2a7fa2b51dc5",
     "parent_folder_id": [1234569799，1234569798],
     "folder_type": 1
 }

5、返回参数

参数	类型	说明
code	int	错误码
msg	string	消息
data	array	返回的接口内容
data.folder_id	int	文件夹id
data.folder_name	string	文件夹名称
data.folder_type	int	文件夹类型，1为我的素材库，2为企业素材库
data.parent_folder_id	int	父级文件夹id
data.parent_folder_name	string	父级文件夹名称
data.is_audit	int	是否开启审核，0为否，1为是
data.auth_type	int	授权范围。1为仅自己可见，2为指定用户/团队可见，4为本公司可见
data.auth_config	array	当授权范围=2时，才会有此配置
data.auth_config.team_id	int	部门id
data.auth_config.user_id	int	用户id

6、返回示例

{
    "code": 0,
    "msg": "success",
    "data": [
         
        {
            "folder_id": 1234569796,
            "folder_name": "test",
            "folder_type": 1,
            "parent_folder_id": 1234569799,
            "parent_folder_name": "test",
            "is_audit": 0,
            "auth_type": 4,
            "auth_config": []
        },
         {
            "folder_id": 1234569797,
            "folder_name": "test",
            "folder_type": 1,
            "parent_folder_id": 1234569798,
            "parent_folder_name": "test",
            "is_audit": 0,
            "auth_type": 2,
            "auth_config": [
                {
                    "team_id": 234,
                    "user_id": 1234
                }
            ]
        }
    ]
}

五、创建素材文件夹

1、接口说明

（1）单次请求最多创建10个文件夹

（2）操作权限为公司管理员

（3）QPM限频为120，一分钟内请求超过120次会返回“请求太频繁”，需要等下一分钟才能再请求

2、接口路径

POST https://xmp-open.mobvista.com/v1/media/folder/add

3、请求参数

公共请求参数：请参考接口请求协议

•Body

参数	类型	必填	说明
data	array	–	data包含所有要创建文件的对象
data.parent_folder_id	int	Y	父级文件夹ID，父级文件夹id=0时表示在素材库下新建一级文件夹
data.folder_name	string	Y	文件夹名称，限200个字符
data.folder_type	int	N	素材库类型，当父级文件夹id=0时必传。1为我的素材库，2为企业素材库
data.is_audit	int	N	是否开启审核，当父级文件夹id=0时选传。0为否，1为是，默认否
data.auth_type	int	N	授权范围，当父级文件夹id=0时必传。1为仅自己可见，2为指定用户/团队可见，4为本公司可见
data.auth_config	array	N	当auth_type=2时必传
data.auth_config.team_id	int	N	部门ID
data.auth_config.user_id	int	N	用户ID。当部门ID和用户ID同时传时，以用户ID为准

4、请求示例

{
    "client_id": "xxxx",
    "timestamp": 1608776690,
    "sign": "05d481dc241a7a1daa5b2a7fa2b51dc5",
    "data": [
        {
            "parent_folder_id": 123,
            "folder_type": 2,
            "folder_name": "test",
            "is_audit": 1,
            "auth_type": 2,
            "auth_config": [
                {
                    "user_id": 22
                },
                {
                    "team_id": 11
                }
            ]
        }
    ]
}

5、返回参数

参数	类型	说明
code	int	错误码
msg	string	消息
data	array	返回的接口内容
data.parent_folder_id	int	父级文件夹id
data.parent_folder_name	string	父级文件夹名称
data.folder_id	int	文件夹id
data.folder_name	string	文件夹名称
data.status	int	状态，0为不成功，1为成功
data.error_msg	string	错误信息

6、返回示例

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "parent_folder_id": 123,
            "folder_id": 1234556,
            "folder_name": "test",
            "status": 1,
            "error_msg": ""
        }
    ]
}

六、修改素材文件夹属性

1、接口说明

（1）单次请求最多修改10个文件夹

（2）操作权限为公司管理员

（3）QPM限频为120，一分钟内请求超过120次会返回“请求太频繁”，需要等下一分钟才能再请求

2、接口路径

POST https://xmp-open.mobvista.com/v1/media/folder/update

3、请求参数

公共请求参数：请参考接口请求协议

•Body

参数	类型	必填	说明
data	array	–	data包含所有对象
data.folder_id	int	Y	文件夹ID
data.folder_name	string	Y	文件夹名称，限200个字符
data.is_audit	int	N	是否开启审核，当父级文件夹id=0时选传。0为否，1为是，默认否
data.auth_type	int	N	授权范围，当父级文件夹id=0时必传。1为仅自己可见，2为指定用户/团队可见，4为本公司可见
data.auth_config	array	N	当auth_type=2时必传
data.auth_config.team_id	int	N	部门ID
data.auth_config.user_id	int	N	用户ID。当部门ID和用户ID同时传时，以用户ID为准

4、请求示例

{
    "client_id": "xmp",
    "timestamp": {{time_now}},
    "sign": "{{sign}}",
    "data": [
        {
            "folder_id": 1100012934,
            "folder_name": "v1.2",
            "auth_type": 4,
            "auth_config": [
                {
                    "user_id": 27
                },
                {
                    "team_id": 11
                }
            ],
            "is_audit": 0
        }
    ]
}

5、返回参数

参数	类型	说明
code	int	错误码
msg	string	消息
data	array	返回的接口内容
data.folder_id	int	文件夹id
data.status	int	状态，0为不成功，1为成功
data.error_msg	string	错误信息

6、返回示例

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "user_material_id": 3510287,
            "status": 1,
            "error_msg": ""
        }
    ]
}

七、获取标签列表

1、接口说明

（1）操作权限为公司管理员

（2）QPM限频为120，一分钟内请求超过120次会返回“请求太频繁”，需要等下一分钟才能再请求

（3）按标签创建时间的升序返回

2、接口路径

POST https://xmp-open.mobvista.com/v1/media/tag/list

3、请求参数

公共请求参数：请参考接口请求协议

•Body

参数	类型	必填	说明
page	int	N	当前页数，默认为1
page_size	int	N	每页数量，默认100，可选1至1000

4、请求示例

{
    "client_id": "xmp",
    "timestamp": {{time_now}},
    "sign": "{{sign}}",
    "page": 1,
    "page_size": 10
}

5、返回参数

参数	类型	说明
code	int	错误码
msg	string	消息
data	array	返回的接口内容
data.tag_id	int	标签id
data.tag_name	string	标签名称
data.level	int	标签层级
data.parent_id	int	父级标签id
data.parent_name	string	父级标签名称
data.full_name_list	array	标签名全称数组

6、返回示例

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "tag_id": 1,
            "tag_name": "电竞",
            "level": 2,
            "parent_id": 10002,
            "parent_name": "默认标签",
            "full_name_list": [
                "默认标签",
                "电竞"
            ]
        }
    ]
}

八、修改标签

1、接口说明

（1）单次请求最多修改10个标签

（2）操作权限为公司管理员

（2）QPM限频为120，一分钟内请求超过120次会返回“请求太频繁”，需要等下一分钟才能再请求

2、接口路径

POST https://xmp-open.mobvista.com/v1/media/tag/update

3、请求参数

公共请求参数：请参考接口请求协议

•Body

参数	类型	必填	说明
data	array	Y	data包含所有对象
data.tag_id	int	Y	标签id
data.name	string	Y	标签名称

4、请求示例

{
    "client_id": "xmp",
    "timestamp": {{time_now}},
    "sign": "{{sign}}",
    "data": [
        {
            "tag_id": 27694,
            "name": "api改的"
        }
    ]
}

5、返回参数

参数	类型	说明
code	int	错误码
msg	string	消息
data	array	返回的接口内容
data.tag_id	int	标签id
data.status	int	状态，0：失败，1：成功
data.error_msg	string	错误信息

6、返回示例

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "tag_id": 27694,
            "status": 1,
            "error_msg": ""
        }
    ]
}

九、创建标签

1、接口说明

（1）单次请求最多创建10个标签，如果新创建的是一级标签，那么其标签对象是汇总渠道素材层级

（2）操作权限为公司管理员

（3）QPM限频为120，一分钟内请求超过120次会返回“请求太频繁”，需要等下一分钟才能再请求

2、接口路径

POST https://xmp-open.mobvista.com/v1/media/tag/add

3、请求参数

公共请求参数：请参考接口请求协议

•Body

参数	类型	必填	说明
data	array	Y	标签名全称

4、请求示例

{
    "client_id": "{{client_id}}",
    "timestamp": {{time_now}},
    "sign": "{{sign}}",
    "data": [
        "lqy/天真/1111111111",
        "lqy/天真/2",
        "lqy/天真1/1",
        "lqy/天真1/1",
        "lqy/天真2/3/4/5",
        "lqy/天真3//",
        "lqy/天真4/不好玩"
    ]
}

5、返回参数

参数	类型	说明
code	int	错误码
msg	string	消息
data	array	返回的接口内容
data.raw_name	string	原始标签名
data.tag_id	int	标签id
data.tag_name	string	标签名称
data.level	int	标签级别
data.full_name_list	array	标签名全称数组
data.status	int	状态
data.error_msg	string	错误信息

6、返回示例

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "raw_name": "lqy/天真/1111111111",
            "tag_id": 28006,
            "tag_name": "1111111111",
            "level": 3,
            "full_name_list": [
                "lqy",
                "天真",
                "1111111111"
            ],
            "status": 0,
            "error_msg": "rpc error: code = Unknown desc = name长度超出限制"
        },
        {
            "raw_name": "lqy/天真/2",
            "tag_id": 28008,
            "tag_name": "2",
            "level": 3,
            "full_name_list": [
                "lqy",
                "天真",
                "2"
            ],
            "status": 1,
            "error_msg": ""
        },
        {
            "raw_name": "lqy/天真1/1",
            "tag_id": 28010,
            "tag_name": "1",
            "level": 3,
            "full_name_list": [
                "lqy",
                "天真1",
                "1"
            ],
            "status": 1,
            "error_msg": ""
        },
        {
            "raw_name": "lqy/天真1/1",
            "tag_id": 28010,
            "tag_name": "1",
            "level": 3,
            "full_name_list": [
                "lqy",
                "天真1",
                "1"
            ],
            "status": 1,
            "error_msg": ""
        },
        {
            "raw_name": "lqy/天真2/3/4/5",
            "tag_id": 28014,
            "tag_name": "5",
            "level": 5,
            "full_name_list": [
                "lqy",
                "天真2",
                "3",
                "4",
                "5"
            ],
            "status": 1,
            "error_msg": ""
        },
        {
            "raw_name": "lqy/天真3//",
            "tag_id": 28015,
            "tag_name": "天真3",
            "level": 2,
            "full_name_list": [
                "lqy",
                "天真3",
                "",
                ""
            ],
            "status": 1,
            "error_msg": ""
        },
        {
            "raw_name": "lqy/天真4/不好玩",
            "tag_id": 28017,
            "tag_name": "不好玩",
            "level": 3,
            "full_name_list": [
                "lqy",
                "天真4",
                "不好玩"
            ],
            "status": 1,
            "error_msg": ""
        }
    ]
}

上一个

素材报表API

下一个

广告管理API

最近修改: 2025-09-04Powered by

大纲