Menu

Creative Library API

1.Obtaining Creative Details


1. Interface Instruction

  • Update frequency: material information and XMP material library synchronous update
  • The operation authority is the company administrator, only support the query of the material information of the enterprise material library.
  • The QPM frequency limit is 120, if the request exceeds 120 times in one minute, it will return "request is too frequent", and you need to wait for the next minute to request again.


2.Interface Path

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


3.Request Parameters

Common request parameters: please refer to Open API Protocol

  • Body

Fields other than is_deleted, page, page_size must be passed at least one

ParameterTypeRequiredInstruction
start_datestringNstart date（creative create time）
YYYY-MM-DD
The start date cannot be later than the end date, and the maximum span cannot exceed 30 days
end_datestringNend date（creative create time） YYYY-MM-DD
Must be uploaded along with start date
user_material_idarrayNcreative local id
md5_file_idarrayNcreative md5
is_deletedintNWhether to delete, if not, return all creatives.
0 means not deleted, 1 means deleted.
folder_idarrayNfolder id
pageintNCurrent page number, the default is 1
page_sizeintNpage size, the default is 200, 1~1000 is available


4.Request Example

{
  "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, # Other than "is_deleted、page、page_size"，at least one of the other fields must be passed
  "folder_id": [1111,22222],
  "page":2,
  "page_size":200
}


5.Return Parameters

ParameterTypeInstruction
codeinterror code
msgstringmessage
dataarrayreturned interface content
data.material_namestringcreative name
data.material_idintcreative id
data.user_material_idintcreative local id
data.md5_file_idstringcreative md5
data.material_typestringcreative type（image，video，other）
data.tagarraytag
data.designerarraydesigner
data.customerarraycreative people
data.widthintwidth
data.heightintheight
data.shapestringshape（horizontal, vertical, square）
data.formatstringformat
data.durationfloatduration, in seconds (returns 0 if it is an image)
data.bit_ratefloatvideo bit rate, the unit is bps (returns 0 if it is an image)
data.urlstringthumbnail url
data.file_urlstringfile url
data.sizefloatFile size, in bytes
data.is_deletedint0 for not deleted, 1 for deleted
data.folder_idintfolder id, operation authority corresponds to the company administrator
data.folder_namestringfolder name
data.audit_statusintaudition status, 0 for pending approval, 1 for approved, -1 for disapproved,return -2 when the folder is not audited
data.created_timedatetimecreative create time
data.updated_timedatetimecreative update time


6.Return Example

{
	"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"
		}
	]
}

2.Upload Creative


1. Interface Instruction

  • A single request can upload up to 10 materials
  • The operation authority is the company administrator


2.Interface Path

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


3.Request Parameter

Common request parameters: please refer to Open API Protocol

  • Body


First-level ParameterSecond-level ParameterTypeRequiredInstruction
data–––data contains all objects to be uploaded
–folder_idintYfolder id
–user_material_namestringYCreative name, limited to 200 characters.
Creative names in the same folder cannot be repeated.
–material_urlstringYCreative URL
Support uploading OSS/S3 address
–material_extstringYCreative extension.
Image：jpg、jpeg、png、bmp；
Video：mp4、mov、avi、mpeg；
Playable：html、htm
–material_typeintYcreative type
1 for image, 2 for video, 10 for playable
–mediastringNChannel
Required when the material type = 10, you can pass: mintegral, applovin, unity, ironsource, only one can be passed
–tag_namestringNtag
name, default is null.
Multiple values can be passed in. When the incoming value does not exist under the company dimension, a new label will be created at the same time. Currently xmp only supports first-level tags
–customer_idintNcreative people, default is null.
Pass any user ID under the company (enable status)
–designer_idintNdesinger, default is null.
Multiple user IDs under the design department (enable status) must be passed.
–audit_statusintNAudit status, the default is approved, 0: pending review, 1: approved, -1: not approved. Only valid when the asset library is enabled for review


4.Request Example

{
     "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", 
             "tag_name": [
                 "tag1","tag2"
             ],
             "folder_id": 12345,
             "designer_id": [
                111，222
             ],
             "customer_id": [
                 333
             ]
         }
     ]
 }


5.Return Parameter


First-level ParameterSecond-level ParameterTypeInstruction
code–interror code
msg–stringmessage
data–arrayreturned interface content
–folder_idintfolder ID
–user_material_idintThe creative ID inside xmp, which is unique.
The field is 0 when upload fails.
–user_material_namestringXMP creative name
–statusintstatus, 0 for failed, 1 for successful
–error_msgstringerror message


6.Return Example

{
     "code": 0,
     "msg": "success",
     "data": [
         {
             "folder_id": 12345,
             "user_material_id": 123445,
             "user_material_name": "sc_upload.png",
             "status": 1,
             "error_msg": ""
         }
     ]
 }


3.Access to Folder List


1.Interface Instruction

  • Returns the folder list of the creative library
  • The operation authority is the company administrator


2.Interface Path

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


3.Request Parameter

Common request parameters: please refer to Open API Protocol

  • Body


ParameterTypeRequiredInstruction
folder_typeintYfolder type
1 for my library, 2 for team library
parent_folder_idintNparent folder ID


4.Request Example

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


5.Return Parameter


First-level ParameterSecond-level ParameterThird-level ParameterTypeInstruction
code––interror code
msg––stringmessage
data––arrayreturned interface content
–folder_id–intfolder ID
–folder_name–stringfolder name
–folder_type–intfolder type
1 for my library, 2 for team library
–parent_folder_id–intparent folder id
–parent_folder_name–stringparent folder name
–is_audit–intwhether to enable auditing
0 for no, 1 for yes
–auth_type–intauthourity type
1为自己可见，2为指定用户/团队可见，4为本公司可见
–auth_config–arrayThis configuration is only available when authorization scope = 2
––team_idintteam ID
––user_idintuser ID


6.Return Example

{
    "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
                }
            ]
        }
    ]
}

4.Create Folder


1.Interface Instruction

  • A single request can upload up to 10 cretives
  • The operation authority is the company administrator


2.Interface Path

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


3.Request Parameter

Common request parameters: please refer to Open API Protocol

  • Body


First-level ParameterSecond-level ParameterThird-level ParameterTypeRequiredInstruction
data––array–data contains all objects to be uploaded
–parent_folder_id–intYparent folder ID
When parent folder ID=0, it means to create a new first-level folder under the creative library
–folder_name–stringYFolder name, 200 characters limit
–folder_type–intNFolder type
1 for my library, 2 for team library
–is_audit–intNWhether to enable auditing, when the parent folder id=0, select and upload.
0 for no, 1 for yes, default no
–auth_type–intNAuthority type.
Required when parent folder id=0. 1 is visible only to yourself, 2 is visible to designated users/teams, 4 is visible to the company.
–auth_config–arrayNRequires when auth_type=2
––team_idintNteam ID
––user_idintNUser ID.
When the department ID and user ID are uploaded at the same time, the user ID shall prevail.


4.Request Example

{
    "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.Return Parameter


First-level ParameterSecond-level ParameterTypeInstruction
code–interror code
msg–stringmessage
data–arrayreturned interface content
–parent_folder_idintparent folder ID
–folder_idintfolder ID
–folder_namestringfolder name
–statusintstatus
0 for unsuccessfully, 1 for successfully
–error_msgstringerror message


6.Return Example

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



Previous
Creative Report API
Next
User Management API
Last modified: 2025-09-04Powered by