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).

共用驗證, 速率限制與錯誤處理見接入方式.