创建文件删除请求
提交单文件或批量文件的异步删除请求
国内用户请注意: 中国大陆用户请使用 https://api.toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://api.toapis.com 请替换为 https://api.toapis.cn.
使用说明
提交手动删除请求, 支持删除一个指定文件或清空当前账号已有文件. 删除异步执行, HTTP 202 表示请求已受理. 使用返回的 id 查询删除进度.
- 删除一个文件: 传
{"scope":"single","file_id":"123"}.file_id从文件列表获取. - 清空当前账号已有文件: 传
{"scope":"all"}, 不传file_id. 请求之后新创建的文件不受影响.
all 只覆盖当前账号在本次请求前已创建的已登记文件. 旧文件可能稍后才登记并纳入处理, 截止时间由服务端确定. 手动删除不受自动清理开关影响. 每次 POST 都创建新请求, 请勿在超时后盲目重发; 接口不提供取消删除功能.
不接受查询参数. 请求体必须是 JSON 对象, 最多 4096 字节, 拒绝未知字段和重复字段, 正文读取期限为 10 秒. 写操作与其他公开账户写接口共享每用户每分钟 10 次的额度. 服务暂时不可用时返回 503.
鉴权
Authorizationstring请求头必填使用系统访问令牌, 格式为 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 不接受模型 API Key, 无需 X-User-Id. 只操作当前认证账号自己的文件和策略, 不合并子账号数据.
请求参数
scopestring请求体必填必填, 选择删除范围:
single: 删除一个指定文件, 必须同时传file_id.all: 清空当前账号已有的全部已登记文件, 不传file_id. 请求之后新创建的文件不受影响.
file_idstring | null请求体要删除的文件 ID, 从文件列表的 data.items[].id 获取, 例如 "123". scope=single 时必填且必须是有效 ID 字符串; scope=all 时省略或传 null. null 按未传处理.
请求示例
curl --request POST \
--url 'https://api.toapis.com/api/v1/user/file/deletion-requests' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"scope":"single","file_id":"123"}'import requests
response = requests.post(
"https://api.toapis.com/api/v1/user/file/deletion-requests",
headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
json={"scope": "single", "file_id": "123"},
timeout=30,
)
response.raise_for_status()
print(response.json())const response = await fetch("https://api.toapis.com/api/v1/user/file/deletion-requests", {
method: "POST",
headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
body: JSON.stringify({"scope": "single", "file_id": "123"}),
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());删除本次受理时间及之前创建的文件:
curl --request POST \
--url 'https://api.toapis.com/api/v1/user/file/deletion-requests' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"scope":"all"}'响应字段
示例使用虚构数据. 通用响应格式见接入方式.
data.idstring删除请求 ID, 用于查询进度.
data.scopestringsingle 表示删除一个指定文件; all 表示清空当前账号已有文件.
data.file_idstring | null单文件范围为文件 ID, 批量范围为 null.
data.created_before_atstring | null批量范围的创建时间截止点, 包含该时刻; 单文件范围为 null.
data.statestringpending 已受理; running 处理中; processed 当前范围已处理; blocked 有阻塞文件或进度复查失败.
data.discovered_countinteger当前已发现的范围内文件数, 迟到登记可能使其增加.
data.deleted_countinteger累计已删除的文件数. 文件从列表移除后, 此计数仍然保留.
data.blocked_countinteger当前被阻塞的文件数. 进度复查本身失败也可令请求 blocked, 此时计数保留上次成功值.
data.created_atstring请求创建时间.
data.updated_atstring进度最近更新时间.
响应示例
{
"code": 0,
"message": "",
"data": {
"id": "456",
"scope": "single",
"file_id": "123",
"created_before_at": null,
"state": "pending",
"discovered_count": 0,
"deleted_count": 0,
"blocked_count": 0,
"created_at": "2026-11-16T08:00:00Z",
"updated_at": "2026-11-16T08:00:00Z"
}
}错误处理
scope, file_id, JSON 或查询参数无效时返回 400. 单文件目标不存在或不属于当前账号时返回 404; 服务暂时不可用时返回 503 (code=13035).
通用鉴权, 限流和错误处理见接入方式.