파일 삭제 요청 생성
단일 파일 또는 일괄 파일의 비동기 삭제 요청
중국 본토 사용자 안내: 중국 본토 사용자는 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.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)입니다.
공통 인증, 속도 제한, 오류 처리는 시작하기를 참고하세요.