ToAPIsToAPIs
使用者檔案

設定檔案保留期

設定或取消目前帳號的檔案保留期限

PUT
/api/v1/user/file/retention

中國大陸用戶請注意: 中國大陸用戶請使用 https://api.toapis.cn 作為接口地址 (Base URL). 文檔示例中的 https://api.toapis.com 請替換為 https://api.toapis.cn.

使用說明

設定目前帳號的檔案保留天數. 例如 7 表示自檔案建立起保留 7 天; 傳送 null 取消自訂設定, 依平台保留規則處理.

平台預設保留 30 天, 實際上限以平台目前設定為準. 自訂天數不能超過此上限: 上限為 30 天時, 30 可以儲存, 31 回傳 400. 使用者保留期在平台自動清理開啟時生效, 適用於既有及之後建立的一般檔案.

清理為非同步. 縮短期限可能使既有檔案於下次清理時被刪除. 延長或取消保留期不會撤銷已開始的刪除流程, 也不影響已提交的手動刪除請求.

不接受查詢參數. 主體必須為 JSON 物件, 最多 4096 位元組, 拒絕未知或重複欄位, 讀取期限為 10 秒. 與其他公開帳戶寫入共用每使用者每分鐘 10 次的額度. 服務暫時無法使用時回傳 503.

驗證

Authorizationstring請求頭必填

使用系統存取權杖, 格式為 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 不接受模型 API Key, 無需 X-User-Id. 僅操作目前驗證帳號自己的檔案與策略, 不合併子帳號資料.

請求參數

retention_daysinteger請求體必填

必填, JSON 正整數或 null. 正整數不能超過目前平台上限, 預設上限為 30 天. 7 表示保留 7 天; null 表示取消自訂期限, 按平台規則處理. 不接受省略, 0, 負數, 小數或數字字串.

請求示例

curl --request PUT \
  --url 'https://api.toapis.com/api/v1/user/file/retention' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"retention_days":7}'
import requests

response = requests.put(
    "https://api.toapis.com/api/v1/user/file/retention",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    json={"retention_days": 7},
    timeout=30,
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.toapis.com/api/v1/user/file/retention", {
  method: "PUT",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({"retention_days": 7}),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

取消使用者自訂期限:

curl --request PUT \
  --url 'https://api.toapis.com/api/v1/user/file/retention' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"retention_days":null}'

回應欄位

範例使用虛構資料. 共用回應格式見接入方式.

data.retention_daysinteger | null

使用者設定的保留天數. null 表示未設定自訂期限, 依平台規則處理, 平台預設保留 30 天.

響應示例

{
  "code": 0,
  "message": "",
  "data": {
    "retention_days": 7
  }
}

錯誤處理

超過目前平台上限時回傳 400 (code=17052), 不儲存本次設定. 錯誤訊息按 Accept-Language 本地化並提供允許的整數範圍; data.params.max 為目前最大天數.

缺少 retention_days, 類型或數值無效, JSON 格式錯誤或帶有查詢參數時回傳 400. 服務暫時無法使用時回傳 503 (code=13035).

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