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
ドキュメントSmart Media HostingBusiness Level API DocumentFile Operation APISimple upload of file

Simple upload of file

PDF
フォーカスモード
フォントサイズ
最終更新日: 2026-01-07 14:15:05

Description

Start simple file upload.
Note:
Requires permissions: admin, space_admin, or upload_file/upload_file_force/begin_upload/begin_upload_force. For details on permissions, refer to the Generate Access Token API.
Used to start a simple upload.
Calling this API will return a series of parameters for PUT simple upload requests and confirming upload completion. The target URL for upload is https://**{Domain}{Path}**, where Domain is the domain field in the response body, and Path is the path field in the response body. For example, https://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/smhxxx/xxx.mp4.
For PUT simple upload, a series of additional request header fields must be specified. The names and values of these fields are included in the headers field of the response body.
When using JS to upload files in the browser, you need to configure Cross-Origin Resource Sharing (CORS) in the bound COS bucket in advance.
After uploading a file to the bucket using the simple method, you need to call the Complete File Upload API.
After the actual upload completes, HTTP 200 OK will be returned by the target URL.
By default, files with the same name will be automatically renamed. The final file path can be obtained from the interface for file upload completion.
It does not automatically create the required parent directories, so you must ensure that all levels of directories in the path exist.
Media libraries of media type do not support uploading files with file extensions.

Request

Request Example

PUT /api/v1/file/`{LibraryId}`/`{SpaceId}`/`{FilePath}`?conflict_resolution_strategy=`{ConflictResolutionStrategy}`&filesize=`{FileSize}`&access_token=`{AccessToken}`&user_id=`{UserId}`&traffic_limit=`{TrafficLimit}`&prefer_same_origin=`{PreferSameOrigin}`

Request Parameter

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
Complete file path, such as foo/bar/file.docx. Please refer to View Directory or Album.
String
Yes
FileSize
Upload file size in bytes (Byte) for judging if available space is sufficient.
String
No
ConflictResolutionStrategy
Handling method when filename conflict, default is rename
ask: returns HTTP 409 Conflict and SameNameDirectoryOrFileExists error code when conflicts with
rename: automatically rename the file when conflicts with
overwrite:
If the target is a directory or album, it defaults to ask and does not support overwrite
If the target is a file, overwrite the existing file
When a file exists in the target space with an earlier version, do not support moving and overwrite.
String
No
AccessToken
Access token, see Generate Access Token
String
Yes
UserId
User identity recognition. When the access token has admin permission and the user identity recognition during token application is empty, it is used to temporarily specify user identity. For details, see Generate Access Token API.
String
No
TrafficLimit
Single link download speed limit, range 100KB/s-100MB/s, Unit B
Number
No
PreferSameOrigin
Whether to keep the same domain name, valid values: true or false
This parameter is valid only when uploading a file with the same name exists in the file path and ConflictResolutionStrategy is set to rename or overwrite.
When this parameter is set, the backend will try to ensure the newly uploaded file uses the same domain name as the original file for upload or download, but in special cases, a different domain name may be used, so this parameter should not be overly relied upon.
Boolean
No

Request Header

x-smh-meta-*: custom metadata.

Request Body

{
  "fullHash": "9fee55123adad49e5090236eead6a8a9edc9caaa0f97b9e38c3713c1b97b9d29",
  "beginningHash": "9faskdfhwek2h3r4kjdsjkahfsdkfhjaksdldc9caaa0f97b9e38c3713c1b97b9d29",
  "size": "2081112",
  "labels":["elephant","animal","Asian elephant"],
  "category":"video",
  "localCreationTime": "2022-07-26T02:58:09Z",
  "localModificationTime": "2022-07-26T02:58:09Z"
}
Request parameters.
Description
Type
Required or Not
beginningHash
fullHash of the first 1MB of the file, used for instant upload: sha256 hash value of the first 1MB of the file
String
No
fullHash
fullHash defined by SMH for instant upload, the following algorithm:
Fetch the first 1MB of the file, calculate its sha256, and use the result as both beginningHash and fullHash.
Continue fetching the next 1MB segment of the file, compute fullHash and the sha256 of the current 1MB data, sha256(Buffer.concat([Buffer.from(fullHash, 'hex'), contentBuffer])), and use the result as fullHash.
Until all calculations are complete, obtain fullHash.
String
No
size
File size for instant upload: Files with size >= 1MB can achieve instant upload.
String
No
labels
File Tag List
String Array
No
category
Customized File Category
String
No
localCreationTime
File local creation time
String
No
localModificationTime
File local modification time
String
No

Response

Response code

Upload task created successfully, return HTTP 201 Created.
beginningHash matches the instant upload file, return HTTP 202 Accepted.
fullHash matches the instant upload file, return HTTP 200 OK.

Response Body

application/json
Response body example (when it does not meet the instant upload condition):
{
    "domain": "examplebucket-1250000000.cos.ap-beijing.myqcloud.com",
    "path": "/smhxxx/xxx.mp4",
    "headers": {
        "Cache-Control": "max-age=31104000",
        "Content-Type": "video/mp4",
        "x-cos-acl": "default",
        "x-cos-storage-class": "STANDARD",
        "Authorization": "q-sign-algorithm=sha1&xxxxxx",
        "x-cos-security-token": "1dleQZoBrm4i5UKcV1ovQM4f63aE3Ldaa508aa686f404316d3628xxx",
        "x-cos-traffic-limit": 204800
    },
    "confirmKey": "7e8481cea3beecbfe5374c904ca9e7496abc612f400c323877310198745270b0",
    "expiration": "2021-07-24T10:34:32.000Z",
    "availableDomainNum":1
}
Response body field description:
Response Parameters
Description
Type
domain
Domain name during actual file upload
String
path
URL path during actual file upload, fixed as "/" in form upload
String
headers
Request header to be specified during actual upload
Key-Value Pair
confirmKey
Parameters for confirming file upload completion
String Array
expiration
Upload information valid period. It will become invalid if it exceeds the validity period. You must call this API again to get new upload parameters.
String
availableDomainNum
Number of available domains
String
Response body example (when beginningHash matches the instant upload condition): Returns 202 with an empty response body.
Response body example (when fully meeting the instant upload condition):
{
  "path": [
    "test.xlsx"
  ],
  "name": "test.xlsx",
  "type": "file",
  "creationTime": "2022-04-08T08:44:59.000Z",
  "modificationTime": "2022-04-08T08:44:59.000Z",
  "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": "2811086",
  "eTag": "\\"b581c674266a2b0ff16a9505b4c52300\\"",
  "crc64": "16293198345556339838",
  "metaData": {},
  "isOverwritten": false,
  "previewByDoc": true,
  "previewByCI": true,
  "previewAsIcon": false,
  "fileType": "excel"
}
Response body field description:
Response Parameters
Description
Type
path
If it is an array of strings, it indicates the final file path. The last element in the array represents the final file name, and the other elements represent each first-level directory name. Because files with the same name may exist and be renamed automatically, the final path here may not equal the designated path when start uploading.
If it is null, it means the directory where the file resides or a certain parent directory has been deleted, and the file can no longer be accessed.
String Array
name
Final file name
String
type
File type
String
creationTime
The time when the file is uploaded for the first time
String
modificationTime
The time when the file was last overwritten
String
contentType
media type
String
size
File size.
String
eTag
File eTag
String
crc64
File CRC64-ECMA182 check value
String
metaData
metadata, if there is no metadata the field does not exist
String
isOverwritten
Whether file overwrite occurs during file upload
Boolean
previewByDoc
Whether the file can be previewed in wps
Boolean
previewByCI
Whether the file can be previewed in Wanxiang
Boolean
previewAsIcon
Whether the preview image is available as an icon
Boolean
fileType
File type: excel, powerpoint, etc.
String

Error Codes

This request operation has no special error messages. For common error messages, see Error Codes.

前の記事へ: Form Upload File次の記事へ: Upload a file in parts

ヘルプとサポート

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

フィードバック