tencent cloud

Smart Media Hosting

Product Introduction
Product Overview
Feature Description
Product Strengths
Use Cases
Basic Concept
Purchase Guide
Quick Start
Create Media Library
Initiate request
Service Level API Document
History
Introduction
API Category
Making API Requests
PaaS Service APIs
Official Cloud Disk APIs
Data Types
Error Codes
Business Level API Document
Introduction
Access Token Operation API
Tenant Space Operation API
File Operation API
Directory or Album Operation API
Recycle Bin Operation API
Quota Operation API
Query Task Operation API
Search Operation API
Historical Version Operations API
Directory and File Batch Operation API
Collection Operation API
Error Codes
SDK Documentation
Android SDK
iOS SDK
HarmonyOS SDK
FAQs
Enterprise Network Disk
Product Introduction
Purchase Guide
Quick Start
FAQs
Service Level Agreement
Glossary

File

PDF
フォーカスモード
フォントサイズ
最終更新日: 2026-01-07 10:49:13

Introduction

This document provides an introduction to file-related APIs and example code

File Upload

Feature Description

The upload method automatically performs fast upload, simple upload, and multi-part upload logic internally. The generated task can be suspended, restored, or canceled externally.

Sample Code

Uploading
try {
let filePath = "local file path";
// Call the uploadObject method of SMHFileApis to perform file upload
let task = SMHFileApis.uploadObject({
spaceId: "spaceId",
libraryId: "libraryId",
body: filePath, // local path
uploadPath: `smh/test.jpg`, // target path
});
task.onStateChange = (state: SMHTransferState) => {
// Job status callback
}
task.confirmKeyInitCallback = (confimKey: string) => {
// Returned after upload confirmKey callback. Used for resumable upload
}
task.onProgress = (progress) => {
// Progress callback
}
task.onFinish = (result?: object, error?: SMHError) => {
// Complete callback
}
// Start task
task.start();

//Other methods
//task.pause() Pause task
//task.cancel() Cancel task
//task.resume() Restart task, can be used together with pause
}catch (e) {
// exception handling
}
Resumable Transfer
try {
let filePath = "local file path";
// Call the uploadObject method of SMHFileApis to perform file upload
let task = SMHFileApis.uploadObject({
spaceId: "spaceId",
libraryId: "libraryId",
body: filePath, // local path
uploadPath: `smh/test.jpg`, // target path
confirmKey:"confirmKey"// confirmKeyInitCallback returns the confirmKey.
});
task.onStateChange = (state: SMHTransferState) => {
// Job status callback
}
task.confirmKeyInitCallback = (confimKey: string) => {
// Returned after upload confirmKey callback. Used for resumable upload
}
task.onProgress = (progress) => {
// Progress callback
}
task.onFinish = (result?: object, error?: SMHError) => {
// Complete callback
}
// Start task
task.start();

//Other methods
//task.pause() Pause task
//task.cancel() Cancel task
//task.resume() Restart task, can be used together with pause
}catch (e) {
// exception handling
}

Parameter Description

Request parameters.
Description
Type
Required or Not
libraryId
Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library
String
Yes
spaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. See create tenant space
String
No
body
File to be uploaded, format: local file path or ArrayBuffer
String/ArrayBuffer
Yes
uploadPath
Target path, such as foo/bar/file.docx
String
Yes
confirmKey
Confirm parameters, specified as the confirmKey field value in the response body when uploading files, for resume upload.
String
No
simpleUploadLimit
The simple upload threshold is 1MB by default. Files less than 1MB will use simple upload, otherwise multipart upload will be used.
Number
No
sliceLength
Chunk size: default 1m
Number
No
conflictResolutionStrategy
Handling method when filename conflict occurs.
ask: returns HTTP 409 Conflict and the SameNameDirectoryOrFileExists error code when conflicts with
rename: automatically rename file when conflicts with
overwrite: returns HTTP 409 Conflict and the SameNameDirectoryOrFileExists error code when the target is a directory, otherwise overwrites the existing file
SMHConflictResolutionStrategy
No
customHeader
Custom request header
Map
No
trafficLimit
Single link download speed limit, range 100KB/s-100MB/s, unit B
Number
No
withInode
Whether to return the inode (file directory ID) after upload
Bool
No

Downloading Files

Feature Description

The download method automatically performs download to local and resume upload logic internally. The generated task can be suspended, restored, or canceled externally.
Note:
The download interface supports resume transfer from breakpoints by default. Ensure that the local path for writing remains unchanged.

Sample Code

try {
// Call the downloadObject method of SMHFileApis to perform file upload
let task = SMHFileApis.downloadObject({
spaceId: "spaceId",
libraryId: "libraryId",
filePath: `smh/test.jpg`, // remote path
savePath: "local path" // local path
})
task.onStateChange = (state: SMHTransferState) => {
// Job status callback
}
task.onProgress = (progress: HttpProgress) => {
// Progress callback
}
task.onFinish = (result?: object, error?: SMHError) => {
// Complete callback
}
// Start task
task.start();
//Other methods
//task.pause() Pause task
//task.cancel() Cancel task
//task.resume() Restart task, can be used together with pause
} catch (e) {
// exception handling
}

Parameter Description

Request parameters.
Description
Type
Required or Not
libraryId
Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library
String
Yes
spaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. See create tenant space
String
No
filePath
Cloud target path, such as foo/bar/file.docx
String
Yes
savePath
local path
String
Yes
historyId
Historical version ID, which is used to obtain different versions of file content
String
No
trafficLimit
Single link download speed limit, range 100KB/s-100MB/s, unit B
Number
No

Retrieving Image/Video Cover Thumbnail

Feature Description

To obtain image/video cover thumbnails.

Sample Code

try {
let result = await SMHFileApis.preview({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/image.jpg"
})
} catch (e) {
// exception handling
}

Parameter Description

Request parameters.
Description
Type
Required or Not
libraryId
Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library
String
Yes
spaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. See create tenant space
String
No
filePath
Cloud target path, such as foo/bar/image.jpg
String
Yes
size
Scale size
String
No
scale
Proportional scaling percentage. This parameter is valid only when Size is not specified.
String
No
widthSize
Scale the width. The height is scaled proportionally when not specified. This parameter is valid only when Size and Scale are not specified.
String
No
heightSize
Scale the height. The width is scaled proportionally when not specified. This parameter is valid only when Size and Scale are not specified.
String
No
frameNumber
Number of frames, frame processing for gif
String
No

Retrieving File Download Links and Info

Feature Description

Get file download link and info.

Sample Code

try {
let result =
await SMHFileApis.downloadInfo({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file.docx"
})
} catch (e) {
// exception handling
}

Parameter Description

Request parameters.
Description
Type
Required or Not
libraryId
Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library
String
Yes
spaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. See create tenant space
String
No
filePath
Cloud target path, such as foo/bar/file.docx
String
Yes
historyId
Historical version ID, which is used to obtain different versions of file content
String
No
trafficLimit
Single link download speed limit, range 100KB/s-100MB/s, unit B
Number
No
contentDisposition
Set the Content-Disposition response header, support inline or attachment
SMHContentDisposition
No
purpose
Purpose, can be set to download or preview, to determine whether to add the file to the recently used file list. If set to preview, the file will be added to the recently used file list; otherwise, it will not.
SMHPurpose
No
pre_check
Whether it is only used for verification to check if the file is previewable and downloadable. After setting this parameter, the returned result does not include cosUrl.
Bool
No

Deletes files.

Feature Description

Deleting files.

Sample Code

try {
let result = await SMHFileApis.deleteFile({
libraryId: "TestLibraryId",
spaceId: "TestSpaceId",
filePath: "foo/bar/file.docx",
permanent: true
});
} catch (e) {
// exception handling
}

Parameter Description

Request parameters.
Description
Type
Required or Not
libraryId
Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library
String
Yes
spaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. See create tenant space
String
No
filePath
Cloud target path, such as foo/bar/file.docx
String
Yes
permanent
When the media library enables the recycle bin, this parameter specifies whether to move the file to the Recycle Bin or permanently delete it. true: permanently delete, false: move to Recycle Bin, default to false.
Bool
No

Copying File

Feature Description

For copying files.

Sample Code

try {
let result = await SMHFileApis.copyFile({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file_new.docx",
copyFrom: "foo/bar/file.docx"
})
} catch (e) {
// exception handling
}

Parameter Description

Request parameters.
Description
Type
Required or Not
libraryId
Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library
String
Yes
spaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. See create tenant space
String
No
filePath
Cloud target path, such as foo/bar/file_new.docx
String
Yes
copyFrom
Cloud path of the source file to be copied, such as foo/bar/file.docx
String
Yes
conflictResolutionStrategy
Handling method when filename conflict occurs, default is rename
ask: returns HTTP 409 Conflict and the SameNameDirectoryOrFileExists error code when conflicts with
rename: automatically rename file when conflicts with
overwrite: returns HTTP 409 Conflict and the SameNameDirectoryOrFileExists error code when the target is a directory, otherwise overwrites the existing file
SMHConflictResolutionStrategy
No

Renaming or Moving Files

Feature Description

For renaming or moving files.

Sample Code

try {
let result = await SMHFileApis.moveFile({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file_new.docx",
from: "foo/bar/file.docx"
})
} catch (e) {
// exception handling
}

Parameter Description

Request parameters.
Description
Type
Required or Not
libraryId
Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library
String
Yes
spaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. See create tenant space
String
No
filePath
Cloud target path, such as foo/bar/file_new.docx
String
Yes
from
Cloud path of the moved source file, such as foo/bar/file.docx
String
Yes
conflictResolutionStrategy
Handling method when filename conflict occurs, default is rename
ask: returns HTTP 409 Conflict and the SameNameDirectoryOrFileExists error code when conflicts with
rename: automatically rename file when conflicts with
overwrite: returns HTTP 409 Conflict and the SameNameDirectoryOrFileExists error code when the target is a directory, otherwise overwrites the existing file
SMHConflictResolutionStrategy
No

Updating File Tags or Categories

Feature Description

Tags for updating files or categorization.

Sample Code

try {
let result = await SMHFileApis.updateTagAndCategory({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file.jpg",
labels: ["elephant","animal","Asian elephant"]
category: "image",
localCreationTime: "2022-07-26T02:58:09Z",
localModificationTime: "2022-07-26T02:58:09Z",
})
} catch (e) {
// exception handling
}

Parameter Description

Request parameters.
Description
Type
Required or Not
libraryId
Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library
String
Yes
spaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. See create tenant space
String
No
filePath
Cloud target path, such as foo/bar/file.docx
String
Yes
labels
File Tag List
String array
No
category
Customized file category
String
No
localCreationTime
Local creation time of the file
String
No
localModificationTime
Local modification time of the file
String
No

Viewing Recently Used File List

Feature Description

View recently used file list.

Sample Code

try {
let result = await SMHFileApis.recentlyUseFile({
libraryId: "libraryId",
spaceId: "spaceId",
filterActionBy: SMHFilterAction.preview,
withPath: true
});
}catch (e) {
// exception handling
}

Parameter Description

Request parameters.
Description
Type
Required or Not
libraryId
Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library
String
Yes
spaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. See create tenant space
String
No
marker
Identifier for sequential page listing, default to first page if not passed
String
No
limit
Number limit for locally listed items in sequential pagination, optional parameter, default to 20 if not passed
String
No
filterActionBy
Filter operation method, return all if not passed, preview only returns preview operation, modify returns edit operation
SMHFilterAction
No
type
Filter file type, currently supported types include:
all: search all files, defaults to all when type is not specified or empty
search all documents, document types: ['pdf', 'powerpoint', 'excel', 'word', 'text']
pdf: search PDF documents only, file extension .pdf
powerpoint: search presentations only, such as .ppt, .pptx, .pot, .potx
excel: search table files only, such as .xls, .xlsx, .ett, .xltx, .csv
word: search documents only, such as .doc, .docx, .dot, .wps, .wpt
text: search plain text only, such as .txt, .asp, .htm
doc, xls, or ppt: search Word, Excel, or Powerpoint documents only, with file extensions .doc(x), .xls(x), or .ppt(x)
array of strings: can be an array of document suffixes, such as ['.ppt', '.doc', '.excel']; or an array of filter types, such as ['pdf', 'powerpoint', 'word']
SMHFileInfoType array
No
withPath
Whether to return the file path, true|false, defaults to false, optional parameter
Bool
No

Querying File Information by File ID

Feature Description

Query file information by file ID.

Sample Code

try {
let result = await SMHFileApis.getFileInfoByInode({
libraryId: "libraryId",
spaceId: "spaceId",
inode: "inode"
})
} catch (e) {
// exception handling
}

Parameter Description

Request parameters.
Description
Type
Required or Not
libraryId
Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library
String
Yes
spaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. See create tenant space
String
No
inode
File ID
String
Yes

Checking File Status

Feature Description

Checking file status.

Sample Code

try {
let result = await SMHFileApis.headFile({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file.docx"
});
} catch (e) {
// exception handling
}

Parameter Description

Request parameters.
Description
Type
Required or Not
libraryId
Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library
String
Yes
spaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. See create tenant space
String
No
filePath
Cloud target path, such as foo/bar/file.docx
String
Yes
historyId
Historical version ID
String
No

Getting HTML Format Document Preview

Feature Description

Used to obtain HTML format document preview.

Sample Code

try {
let result = await SMHFileApis.previewHtml({
libraryId: "libraryId",
spaceId: "spaceId",
filePath: "foo/bar/file.docx"
})
} catch (e) {
// exception handling
}

Parameter Description

Request parameters.
Description
Type
Required or Not
libraryId
Media Library ID, obtained after creating a media library in the Media Hosting console. See Create Media Library
String
Yes
spaceId
Space ID. If the media library is in single-tenant mode, this parameter is fixed as hyphen (`-`); if the media library is in multi-tenant mode, you must specify this parameter. See create tenant space
String
No
filePath
Cloud target path, such as foo/bar/file.docx
String
Yes
historyId
Historical version ID, which is used to obtain different versions of file content
String
No
type
Document preview method: if set to "pic", preview the document homepage in jpg format; otherwise, preview it in html format.
SMHPreviewType
No

ヘルプとサポート

この記事はお役に立ちましたか?

フィードバック