文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>智能媒资托管>业务级 API 文档>文件操作接口>删除文件

删除文件

最近更新时间：2025-11-19 14:56:22

我的收藏

本页目录：

功能描述

用于删除文件。
说明：
要求权限：admin、space_admin 或 delete_file（未开启回收站或 Permanent 为 0）/delete_file_permanent（开启回收站且 Permanent 为 1）有关权限详情请参见 生成访问令牌接口。
如果媒体库启用了回收站功能，在 Permanent 请求参数不为1的情况下，该接口不会永久删除文件，而是将文件移入回收站，可通过相关接口永久删除或恢复回收站内的文件，或直接清空回收站。

请求

请求示例

DELETE /api/v1/file/`{LibraryId}`/`{SpaceId}`/`{FilePath}`?permanent=`{Permanent}`&access_token=`{AccessToken}`&user_id=`{UserId}`

请求参数

请求参数
描述
类型
是否必选
LibraryId
媒体库 ID，在媒体托管控制台创建媒体库后获取，请参见 创建媒体库
String
是
SpaceId
空间 ID
如果媒体库为单租户模式，则该参数固定为连字符(`-`)
如果媒体库为多租户模式，则该参数为 创建租户空间 接口返回的空间 ID
String
是
FilePath
完整文件路径，例如 foo/bar2/file.docx，获取请参见 查看文件详情
String
是
Permanent
当媒体库开启回收站时，则该参数指定将文件移入回收站还是永久删除文件
1: 永久删除，0: 移入回收站，默认为0
Integer
否
AccessToken
访问令牌，获取请参见 生成访问令牌
String
是
UserId
用户身份识别，当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份，详情请参见 生成访问令牌接口
String
否

请求体

该请求无请求体。

响应

响应码

删除成功，返回 HTTP 204 No Content（未开启回收站或开启回收站后永久删除）或 HTTP 200 OK（开启回收站后将文件移入回收站）。

响应体

空，无响应体（未开启回收站或开启回收站后永久删除）或 application/json（开启回收站后将文件移入回收站）。
响应体示例：（开启回收站后将文件移入回收站）
{
  "recycledItemId": 392
}
响应体字段说明：
响应参数
描述
类型
recycledItemId
回收站项目 ID，用于从回收站永久删除或恢复指定项目
Integer

错误码

该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。

实际案例

案例一：开启回收站功能的媒体库，正常删除文件

请求

DELETE /api/v1/file/smhxxx/spacexxx/hello.txt?access_token=*** HTTP/1.1
Host: smhxxx.api.tencentsmh.cn
User-Agent: curl/8.5.0
Accept: */*


响应

HTTP/1.1 200 OK
Date: Thu, 13 Nov 2025 12:03:07 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 23
Server: nginx/1.29.0
X-Request-Id: 1134a11c72aae4f9436150715ffxxxxx

{"recycledItemId":1221}

案例二：开启回收站功能的媒体库，永久删除文件

请求

DELETE /api/v1/file/smhxxx/spacexxx/hello.txt?permanent=1&access_token=*** HTTP/1.1
Host: smhxxx.api.tencentsmh.cn
User-Agent: curl/8.5.0
Accept: */*


响应

HTTP/1.1 204 No Content
Date: Thu, 13 Nov 2025 11:59:07 GMT
Server: nginx/1.29.0
X-Request-Id: 31cd0b6354901448bbfff8602fexxxxx


案例三：未开启回收站功能的媒体库，正常删除文件

请求

DELETE /api/v1/file/smhxxx/spacexxx/hello.txt?access_token=*** HTTP/1.1
Host: smhxxx.api.tencentsmh.cn
User-Agent: curl/8.5.0
Accept: */*


响应

HTTP/1.1 204 No Content
Date: Thu, 13 Nov 2025 12:06:13 GMT
Server: nginx/1.29.0
X-Request-Id: 39c5971c236e7d49ddd4f383f15xxxxx


案例四：删除空间中不存在的文件

请求

DELETE /api/v1/file/smhxxx/spacexxx/path/to/non_existent_file.txt?access_token=*** HTTP/1.1
Host: smhxxx.api.tencentsmh.cn
User-Agent: curl/8.5.0
Accept: */*


响应

HTTP/1.1 404 Not Found
Date: Thu, 13 Nov 2025 12:07:28 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 141
Server: nginx/1.29.0
X-Request-Id: 7ed191d7a75dd90ccc8ff2905d8xxxxx

{"status":404,"code":"FileNotFound","message":"File not found.","requestId":"7ed191d7a75dd90xxxxxf2905d8b6ef1","qualifier":"","revision":""}

中国站
目录