> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# 파일 직접 업로드하기

> 사전 서명된 단일 파트 및 멀티파트 업로드로 Whop 스토리지에 파일을 업로드하세요

Whop 업로드는 **스토리지 직접 업로드** 방식입니다. [Create File](https://docs.whop.com/ko/api-reference/files/create-file.md)을 호출하면 Whop은 API를 통해 바이트를 받지 않습니다. 대신 파일 레코드를 생성하고, 바이트를 직접 `PUT`할 **사전 서명된 업로드 URL**을 돌려줍니다. 바이트가 Whop의 스토리지에 도착하면 파일을 사용할 수 있게 됩니다.

이는 SDK의 `files.create` 및 `files.retrieve` 메서드 뒤에 있는 원시 2단계 흐름입니다. 브라우저에서 업로드하거나(바이트가 서버를 거치지 않도록) SDK가 없는 언어로 작업할 때 사용하세요. 멀티파트가 필요할 만큼 큰 파일을 보낼 때도 이 방식을 사용합니다.

> [!NOTE]
>
> `/files` 엔드포인트에는 API 버전 `2026-08-21-1` 이상이 필요합니다. 아래의 모든 요청은 `Api-Version-Date` 헤더로 버전을 고정합니다. [API 버전](https://docs.whop.com/ko/developer/api/versioning.md)을 참고하세요.

## 업로드 수명 주기

파트가 하나든 여러 개든 모든 업로드는 세 단계로 이루어집니다:

1. 파일 레코드를 **생성**합니다 → Whop이 사전 서명된 대상을 반환하고 파일은 `pending` 상태로 시작합니다.
2. 사전 서명된 URL로 바이트를 바로 **업로드**합니다.
3. `upload_status`가 `ready`가 될 때까지 [Retrieve File](https://docs.whop.com/ko/api-reference/files/retrieve-file.md)을 **폴링**합니다. 그러면 `url`과 `size`가 채워지고, Whop이 문서를 받는 모든 곳에 파일 ID를 첨부할 수 있습니다.

처리가 끝날 때까지 파일의 `url`과 `size`는 `null`로 유지됩니다. `upload_status`는 `pending` → `processing` → `ready`(또는 `failed`) 순으로 진행됩니다.

## 단일 파트 업로드

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

**1. 파일 생성하기**

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

```bash theme={null}
curl https://api.whop.com/api/v1/files \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "terms.pdf", "visibility": "private" }'
```

```json theme={null}
{
  "object": "file",
  "id": "file_XXXXXXXX",
  "filename": "terms.pdf",
  "content_type": "application/pdf",
  "size": null,
  "url": null,
  "removed_by_moderation": false,
  "upload_status": "pending",
  "visibility": "private",
  "created_at": "2026-08-21T18:24:00.000Z",
  "width": null,
  "height": null,
  "blurhash": null,
  "duration_seconds": null,
  "waveform_url": null,
  "upload_url": "https://upload.whop.com/uploads/...&signature=...",
  "upload_headers": { "Content-Type": "application/pdf" },
  "multipart_upload_id": null,
  "multipart_upload_urls": null,
  "multipart_chunk_size": null
}
```

**2. 바이트 업로드하기**

`upload_headers`의 모든 헤더와 함께 파일 내용을 `upload_url`로 `PUT`하세요. 이 요청은 `api.whop.com`이 **아니라** Whop의 파일 스토리지로 바로 전송되며, Whop `Authorization` 헤더를 포함하지 않습니다. 자격 증명은 사전 서명된 URL에 포함되어 있습니다.

```bash theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @terms.pdf
```

> [!WARNING]
>
> 사전 서명된 URL은 발급 후 1시간이 지나면 만료됩니다. 업로드 직전에 파일을 생성하고, 오랜 지연 후 `PUT`이 `403`으로 실패하면 새 URL을 요청하세요. 멀티파트 파트 URL은 더 빨리, 15분 후에 만료됩니다.

**3. 준비될 때까지 폴링하기**

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

```bash theme={null}
curl https://api.whop.com/api/v1/files/file_XXXXXXXX \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1"
```

```json theme={null}
{
  "object": "file",
  "id": "file_XXXXXXXX",
  "filename": "terms.pdf",
  "content_type": "application/pdf",
  "size": 82345,
  "url": "https://files.whop.com/...&signature=...",
  "removed_by_moderation": false,
  "upload_status": "ready",
  "visibility": "private",
  "created_at": "2026-08-21T18:24:00.000Z",
  "width": null,
  "height": null,
  "blurhash": null,
  "duration_seconds": null,
  "waveform_url": null
}
```

## 멀티파트 업로드

큰 파일은 여러 파트로 나누어 업로드하세요. Whop은 파트마다 사전 서명된 URL을 하나씩 반환합니다. 파트를 업로드한 다음(선택적으로 병렬로), Whop에 조립하도록 요청합니다.

단일 업로드 요청은 5GB를 초과할 수 없으므로 **5GB를 넘으면 멀티파트가 필수**입니다. 하나의 긴 업로드가 불안정해지는 약 100MB 이상에서도 멀티파트를 사용하는 것이 좋습니다. 마지막을 제외한 모든 파트가 최소 5MB여야 하므로 파일은 5MB보다 커야 합니다.

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

Whop이 반환할 사전 서명된 파트 URL의 개수를 알 수 있도록 `multipart: true`와 전체 `byte_size`를 전달하세요. 응답에는 `multipart_upload_id`, `part_number`마다 하나씩의 사전 서명된 `url`, 그리고 마지막을 제외한 각 파트의 크기인 `multipart_chunk_size`(바이트)가 포함됩니다.

```bash theme={null}
curl https://api.whop.com/api/v1/files \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "release.mp4", "visibility": "private", "multipart": true, "byte_size": 12582912 }'
```

```json theme={null}
{
  "object": "file",
  "id": "file_XXXXXXXX",
  "filename": "release.mp4",
  "content_type": "video/mp4",
  "size": null,
  "url": null,
  "removed_by_moderation": false,
  "upload_status": "pending",
  "visibility": "private",
  "created_at": "2026-08-21T18:24:00.000Z",
  "width": null,
  "height": null,
  "blurhash": null,
  "duration_seconds": null,
  "waveform_url": null,
  "upload_url": null,
  "upload_headers": {},
  "multipart_upload_id": "2~aBcD1234...",
  "multipart_upload_urls": [
    { "part_number": 1, "url": "https://upload.whop.com/...&part_number=1&signature=..." },
    { "part_number": 2, "url": "https://upload.whop.com/...&part_number=2&signature=..." },
    { "part_number": 3, "url": "https://upload.whop.com/...&part_number=3&signature=..." }
  ],
  "multipart_chunk_size": 5242880
}
```

> [!NOTE]
>
> 멀티파트 업로드는 각 5MB인 파트를 최대 **10,000개**까지 지원하며, 이는 약 50GB입니다. 더 많은 파트가 필요한 `byte_size`는 `400`으로 거부됩니다.

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

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

```javascript theme={null}
import { readFile } from "node:fs/promises";

const bytes = await readFile("./release.mp4");
const chunkSize = created.multipart_chunk_size;

const parts = await Promise.all(
  created.multipart_upload_urls.map(async ({ part_number, url }) => {
    const start = (part_number - 1) * chunkSize;
    const chunk = bytes.subarray(start, start + chunkSize);

    const res = await fetch(url, { method: "PUT", body: chunk });
    if (!res.ok) throw new Error(`Part ${part_number} failed: ${res.status}`);

    // The ETag header comes back quoted, e.g. "\"abc123\"" — send it as-is.
    return { part_number, etag: res.headers.get("etag") };
  }),
);
```

**3. 업로드 완료하기**

`multipart_upload_id`와 모든 파트의 `part_number` + `etag`를 [Complete File Multipart Upload](https://docs.whop.com/ko/api-reference/files/complete-file-multipart-upload.md)에 전달하세요. Whop이 파트를 최종 파일로 조립합니다.

```bash theme={null}
curl https://api.whop.com/api/v1/files/file_XXXXXXXX/complete \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1" \
  -H "Content-Type: application/json" \
  -d '{
    "multipart_upload_id": "2~aBcD1234...",
    "multipart_parts": [
      { "part_number": 1, "etag": "\"5eb63bbbe01eeed093cb22bb8f5acdc3\"" },
      { "part_number": 2, "etag": "\"9e107d9d372bb6826bd81d3542a419d6\"" },
      { "part_number": 3, "etag": "\"e4d909c290d0fb1ca068ffaddf22cbd0\"" }
    ]
  }'
```

> [!WARNING]
>
> 모든 파트는 업로드할 때 반환된 정확한 `ETag`와 함께 순서대로 나열해야 합니다. 알 수 없는 `multipart_upload_id`나 일치하지 않는 `ETag`는 `400`으로 반환됩니다. 문제가 된 파트를 다시 업로드하고 다시 완료하세요.

**4. 준비될 때까지 폴링하기**

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

## 공개 범위 선택하기

`visibility`는 생성 시 설정하며 이후에는 변경할 수 없습니다:

| 공개 범위 | 받는 `url` | 용도 |
| - | - | - |
| `private`(기본값) | 만료되는 서명된 URL | 법률 문서, 분쟁 증거, 사용자 업로드 |
| `public` | 영구적인 서명되지 않은 콘텐츠 전송 네트워크 URL | 상품 이미지, 썸네일, 브랜딩, 마케팅 자료 |

공개 파일은 Whop의 CDN에 캐시되며 철회할 수 없으므로, 민감한 파일에는 기본값인 `private`을 유지하세요. 자세한 내용은 [파일 업로드하기](https://docs.whop.com/ko/developer/guides/upload-files.md#accessing-private-files)를 참고하세요.

## 업로드된 파일 사용하기

파일이 `ready` 상태가 되면 Whop이 문서를 받는 모든 곳에 해당 `id`를 전달하세요. 예를 들어 [분쟁](https://docs.whop.com/ko/api-reference/disputes/dispute) 증거나 계정의 법률 문서가 있습니다.

## 다음 단계

> [card] [파일 업로드하기(SDK)](https://docs.whop.com/ko/developer/guides/upload-files.md)
>
> SDK의 `files.create` 및 `files.retrieve` 메서드가 이 흐름을 감싸는 방식.

> [card] [Create File](https://docs.whop.com/ko/api-reference/files/create-file.md)
>
> 생성 엔드포인트의 전체 요청 및 응답 레퍼런스.

> [card] [Complete File Multipart Upload](https://docs.whop.com/ko/api-reference/files/complete-file-multipart-upload.md)
>
> 멀티파트 파트 조립에 대한 레퍼런스.

> [card] [API 버전](https://docs.whop.com/ko/developer/api/versioning.md)
>
> `Api-Version-Date` 헤더가 중요한 이유와 고정하는 방법.


## Related topics

- [파일 업로드](https://docs.whop.com/ko/developer/guides/upload-files.md)
- [인증 RFI 처리하기](https://docs.whop.com/ko/developer/verification/rfis.md)
- [Files API](https://docs.whop.com/ko/api-reference/files/file.md)
