Skip to main content
Whop 업로드는 스토리지 직접 업로드 방식입니다. Create File을 호출하면 Whop은 API를 통해 바이트를 받지 않습니다. 대신 파일 레코드를 생성하고, 바이트를 직접 PUT할 사전 서명된 업로드 URL을 돌려줍니다. 바이트가 Whop의 스토리지에 도착하면 파일을 사용할 수 있게 됩니다. 이는 SDK의 files.create 및 files.retrieve 메서드 뒤에 있는 원시 2단계 흐름입니다. 브라우저에서 업로드하거나(바이트가 서버를 거치지 않도록) SDK가 없는 언어로 작업할 때 사용하세요. 멀티파트가 필요할 만큼 큰 파일을 보낼 때도 이 방식을 사용합니다.
/files 엔드포인트에는 API 버전 2026-08-21-1 이상이 필요합니다. 아래의 모든 요청은 Api-Version-Date 헤더로 버전을 고정합니다. API 버전을 참고하세요.

업로드 수명 주기

파트가 하나든 여러 개든 모든 업로드는 세 단계로 이루어집니다:
  1. 파일 레코드를 생성합니다 → Whop이 사전 서명된 대상을 반환하고 파일은 pending 상태로 시작합니다.
  2. 사전 서명된 URL로 바이트를 바로 업로드합니다.
  3. upload_status가 ready가 될 때까지 Retrieve File을 폴링합니다. 그러면 url과 size가 채워지고, Whop이 문서를 받는 모든 곳에 파일 ID를 첨부할 수 있습니다.
처리가 끝날 때까지 파일의 url과 size는 null로 유지됩니다. upload_status는 pending → processing → ready(또는 failed) 순으로 진행됩니다.

단일 파트 업로드

수백 메가바이트 미만의 파일에는 단일 PUT을 사용하세요.
1

파일 생성하기

filename과 선택적으로 visibility(기본값 private)를 전송하세요. 응답의 upload_url은 바이트를 보낼 곳이고, upload_headers는 함께 보내야 하는 헤더입니다.
2

바이트 업로드하기

upload_headers의 모든 헤더와 함께 파일 내용을 upload_url로 PUT하세요. 이 요청은 api.whop.com이 아니라 Whop의 파일 스토리지로 바로 전송되며, Whop Authorization 헤더를 포함하지 않습니다. 자격 증명은 사전 서명된 URL에 포함되어 있습니다.
사전 서명된 URL은 발급 후 1시간이 지나면 만료됩니다. 업로드 직전에 파일을 생성하고, 오랜 지연 후 PUT이 403으로 실패하면 새 URL을 요청하세요. 멀티파트 파트 URL은 더 빨리, 15분 후에 만료됩니다.
3

준비될 때까지 폴링하기

upload_status가 ready가 될 때까지 ID로 파일을 조회하세요. 그러면 url 필드에 다운로드 링크가 담깁니다. 파일이 public이면 영구적인 콘텐츠 전송 네트워크 URL이, private이면 서명된 만료형 URL이 담깁니다.

멀티파트 업로드

큰 파일은 여러 파트로 나누어 업로드하세요. Whop은 파트마다 사전 서명된 URL을 하나씩 반환합니다. 파트를 업로드한 다음(선택적으로 병렬로), Whop에 조립하도록 요청합니다. 단일 업로드 요청은 5GB를 초과할 수 없으므로 5GB를 넘으면 멀티파트가 필수입니다. 하나의 긴 업로드가 불안정해지는 약 100MB 이상에서도 멀티파트를 사용하는 것이 좋습니다. 마지막을 제외한 모든 파트가 최소 5MB여야 하므로 파일은 5MB보다 커야 합니다.
1

멀티파트를 활성화하여 파일 생성하기

Whop이 반환할 사전 서명된 파트 URL의 개수를 알 수 있도록 multipart: true와 전체 byte_size를 전달하세요. 응답에는 multipart_upload_id, part_number마다 하나씩의 사전 서명된 url, 그리고 마지막을 제외한 각 파트의 크기인 multipart_chunk_size(바이트)가 포함됩니다.
멀티파트 업로드는 각 5MB인 파트를 최대 10,000개까지 지원하며, 이는 약 50GB입니다. 더 많은 파트가 필요한 byte_size는 400으로 거부됩니다.
2

각 파트를 업로드하고 ETag 저장하기

파일을 multipart_chunk_size 바이트 크기의 청크로 나누고(마지막 파트는 더 작을 수 있음) 각 청크를 해당 파트의 url로 PUT하세요. 각 업로드 응답은 ETag 헤더를 반환합니다. 완료할 때 둘 다 필요하므로 part_number와 함께 보관하세요.
3

업로드 완료하기

multipart_upload_id와 모든 파트의 part_number + etag를 Complete File Multipart Upload에 전달하세요. Whop이 파트를 최종 파일로 조립합니다.
모든 파트는 업로드할 때 반환된 정확한 ETag와 함께 순서대로 나열해야 합니다. 알 수 없는 multipart_upload_id나 일치하지 않는 ETag는 400으로 반환됩니다. 문제가 된 파트를 다시 업로드하고 다시 완료하세요.
4

준비될 때까지 폴링하기

단일 파트 업로드와 마찬가지로 upload_status가 ready가 될 때까지 파일을 조회하세요. 그러면 ID를 첨부할 수 있습니다.

공개 범위 선택하기

visibility는 생성 시 설정하며 이후에는 변경할 수 없습니다: 공개 파일은 Whop의 CDN에 캐시되며 철회할 수 없으므로, 민감한 파일에는 기본값인 private을 유지하세요. 자세한 내용은 파일 업로드하기를 참고하세요.

업로드된 파일 사용하기

파일이 ready 상태가 되면 Whop이 문서를 받는 모든 곳에 해당 id를 전달하세요. 예를 들어 분쟁 증거나 계정의 법률 문서가 있습니다.

다음 단계

파일 업로드하기(SDK)

SDK의 files.create 및 files.retrieve 메서드가 이 흐름을 감싸는 방식.

Create File

생성 엔드포인트의 전체 요청 및 응답 레퍼런스.

Complete File Multipart Upload

멀티파트 파트 조립에 대한 레퍼런스.

API 버전

Api-Version-Date 헤더가 중요한 이유와 고정하는 방법.