ToAPIsToAPIs
用户文件

创建文件删除请求

提交单文件或批量文件的异步删除请求

POST
/api/v1/user/file/deletion-requests

国内用户请注意: 中国大陆用户请使用 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.scopestring

single 表示删除一个指定文件; all 表示清空当前账号已有文件.

data.file_idstring | null

单文件范围为文件 ID, 批量范围为 null.

data.created_before_atstring | null

批量范围的创建时间截止点, 包含该时刻; 单文件范围为 null.

data.statestring

pending 已受理; 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).

通用鉴权, 限流和错误处理见接入方式.