ToAPIsToAPIs
사용자 파일

파일 삭제 요청 생성

단일 파일 또는 일괄 파일의 비동기 삭제 요청

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

중국 본토 사용자 안내: 중국 본토 사용자는 https://api.toapis.cn 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 https://api.toapis.com 을 https://api.toapis.cn 로 바꿔 주세요.

동작

파일 하나 또는 현재 계정의 기존 파일 전체 삭제를 요청합니다. 삭제는 비동기이며 HTTP 202는 접수를 뜻합니다. 반환된 id로 삭제 진행 상황을 확인합니다.

  • 파일 하나 삭제: {"scope":"single","file_id":"123"}을 전송합니다. ID는 파일 목록에서 확인합니다.
  • 기존 파일 전체 삭제: {"scope":"all"}을 보내고 file_id는 생략합니다. 요청 이후 생성한 파일은 영향을 받지 않습니다.

all은 이번 요청 이전에 생성된 본인 등록 파일을 대상으로 합니다. 늦게 등록된 이전 파일도 포함될 수 있으며 경계 시각은 서버가 정합니다. 수동 삭제는 자동 정리 스위치와 무관합니다. POST마다 새 요청이 생성되므로 시간 초과 후 무조건 재전송하지 마세요. 취소 기능은 없습니다.

쿼리 매개변수는 허용하지 않습니다. 본문은 최대 4096바이트의 JSON 객체이며 알 수 없거나 중복된 필드는 거부합니다. 본문 읽기 제한은 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)입니다.

공통 인증, 속도 제한, 오류 처리는 시작하기를 참고하세요.