> ## 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.

# Téléverser des fichiers directement

> Téléversez des fichiers vers le stockage Whop avec des téléversements présignés en une seule partie ou en plusieurs parties

Les téléversements Whop se font **directement vers le stockage**. Lorsque vous appelez [Create File](https://docs.whop.com/fr/api-reference/files/create-file.md), Whop ne reçoit pas vos octets via l'API. Il crée un enregistrement de fichier et renvoie une **URL de téléversement présignée** vers laquelle vous envoyez vous-même les octets avec `PUT`. Le fichier devient utilisable dès que ces octets arrivent dans le stockage de Whop.

Il s'agit du flux brut en deux étapes qui se cache derrière les méthodes `files.create` et `files.retrieve` du SDK. Utilisez-le lorsque vous téléversez depuis le navigateur (afin que les octets ne passent jamais par votre serveur) ou que vous travaillez dans un langage sans SDK. C'est aussi ainsi que vous envoyez des fichiers suffisamment volumineux pour nécessiter un téléversement en plusieurs parties.

> [!NOTE]
>
> Les endpoints `/files` nécessitent la version d'API `2026-08-21-1` ou ultérieure. Chaque requête ci-dessous l'épingle avec l'en-tête `Api-Version-Date`. Consultez [Versions de l'API](https://docs.whop.com/fr/developer/api/versioning.md).

## Le cycle de vie d'un téléversement

Chaque téléversement comporte trois étapes, qu'il s'agisse d'une seule partie ou de plusieurs :

1. **Créez** l'enregistrement du fichier → Whop renvoie une destination présignée et le fichier démarre avec le statut `pending`.
2. **Téléversez** les octets directement vers les URL présignées.
3. **Interrogez** [Retrieve File](https://docs.whop.com/fr/api-reference/files/retrieve-file.md) jusqu'à ce que `upload_status` vaille `ready` — `url` et `size` sont alors renseignés et l'ID du fichier peut être joint partout où Whop accepte un document.

Les champs `url` et `size` d'un fichier restent à `null` jusqu'à la fin du traitement. `upload_status` passe de `pending` → `processing` → `ready` (ou `failed`).

## Téléversement en une seule partie

Utilisez un seul `PUT` pour tout fichier de moins de quelques centaines de mégaoctets.

**1. Créer le fichier**

Envoyez le `filename` et, éventuellement, une `visibility` (`private` par défaut). Le champ `upload_url` de la réponse indique où envoyer les octets, et `upload_headers` contient les en-têtes que vous devez envoyer avec eux.

```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. Téléverser les octets**

Envoyez le contenu du fichier vers `upload_url` avec `PUT`, en incluant chaque en-tête de `upload_headers`. Cette requête est adressée directement au stockage de fichiers de Whop, **et non** à `api.whop.com`, et ne comporte aucun en-tête `Authorization` Whop — les identifiants sont intégrés à l'URL présignée.

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

> [!WARNING]
>
> L'URL présignée expire une heure après son émission. Créez le fichier juste avant de téléverser, et demandez-en une nouvelle si un `PUT` échoue avec une erreur `403` après un long délai. Les URL des parties d'un téléversement en plusieurs parties expirent plus tôt, au bout de 15 minutes.

**3. Interroger jusqu'à ce que le fichier soit prêt**

Récupérez le fichier par son ID jusqu'à ce que `upload_status` passe à `ready`. Le champ `url` contient alors un lien de téléchargement : une URL permanente de réseau de diffusion de contenu lorsque le fichier est `public`, ou une URL signée qui expire lorsqu'il est `private`.

```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
}
```

## Téléversement en plusieurs parties

Pour les fichiers volumineux, téléversez-les en plusieurs parties. Whop renvoie une URL présignée par partie. Vous les téléversez (éventuellement en parallèle), puis vous demandez à Whop de les assembler.

Le téléversement en plusieurs parties est **obligatoire au-delà de 5 Go**, car une seule requête de téléversement ne peut pas dépasser cette taille. Il est également recommandé au-delà d'environ 100 Mo, où un long téléversement unique est fragile. Le fichier doit dépasser 5 Mo, car chaque partie, à l'exception de la dernière, doit faire au moins 5 Mo.

**1. Créer le fichier avec le téléversement en plusieurs parties activé**

Transmettez `multipart: true` et la taille totale `byte_size` afin que Whop sache combien d'URL de parties présignées renvoyer. La réponse contient un `multipart_upload_id`, une `url` présignée par `part_number`, et le `multipart_chunk_size` (en octets) que doit respecter chaque partie, à l'exception de la dernière.

```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]
>
> Les téléversements en plusieurs parties prennent en charge au maximum **10 000 parties** de 5 Mo chacune — soit environ 50 Go. Un `byte_size` qui nécessiterait davantage de parties est refusé avec une erreur `400`.

**2. Téléverser chaque partie et récupérer son ETag**

Découpez le fichier en blocs de `multipart_chunk_size` octets (la dernière partie peut être plus petite) et envoyez chaque bloc avec `PUT` vers l'`url` de la partie correspondante. Chaque réponse de téléversement renvoie un **en-tête `ETag`** — conservez-le avec le `part_number`, vous aurez besoin des deux pour terminer.

```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. Finaliser le téléversement**

Renvoyez le `multipart_upload_id` ainsi que le `part_number` + `etag` de chaque partie à [Complete File Multipart Upload](https://docs.whop.com/fr/api-reference/files/complete-file-multipart-upload.md). Whop assemble les parties pour former le fichier final.

```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]
>
> Chaque partie doit être listée, dans l'ordre, avec l'`ETag` exact renvoyé lors de son téléversement. Un `multipart_upload_id` inconnu ou un `ETag` qui ne correspond pas renvoie une erreur `400` — téléversez à nouveau la partie en cause et finalisez de nouveau.

**4. Interroger jusqu'à ce que le fichier soit prêt**

Comme pour les téléversements en une seule partie, récupérez le fichier jusqu'à ce que `upload_status` vaille `ready`. L'ID peut alors être joint.

## Choisir une visibilité

Vous définissez `visibility` lors de la création et ne pouvez plus la modifier ensuite :

| Visibilité | `url` obtenue | À utiliser pour |
| - | - | - |
| `private` (par défaut) | URL signée qui expire | Documents juridiques, preuves de litige, fichiers téléversés par les utilisateurs |
| `public` | URL permanente et non signée de réseau de diffusion de contenu | Images de produits, miniatures, éléments de marque, supports marketing |

Les fichiers publics sont mis en cache sur le CDN de Whop et ne peuvent pas être révoqués : conservez donc la valeur par défaut `private` pour tout contenu sensible. Consultez [Téléverser des fichiers](https://docs.whop.com/fr/developer/guides/upload-files.md#accessing-private-files) pour en savoir plus.

## Utiliser un fichier téléversé

Une fois qu'un fichier est `ready`, transmettez son `id` partout où Whop accepte un document — par exemple comme preuve dans un [litige](https://docs.whop.com/fr/api-reference/disputes/dispute) ou parmi les documents juridiques d'un compte.

## Étapes suivantes

> [card] [Téléverser des fichiers (SDK)](https://docs.whop.com/fr/developer/guides/upload-files.md)
>
> Comment les méthodes `files.create` et `files.retrieve` du SDK encapsulent ce flux.

> [card] [Create File](https://docs.whop.com/fr/api-reference/files/create-file.md)
>
> Référence complète des requêtes et réponses de l'endpoint de création.

> [card] [Complete File Multipart Upload](https://docs.whop.com/fr/api-reference/files/complete-file-multipart-upload.md)
>
> Référence pour l'assemblage des parties d'un téléversement en plusieurs parties.

> [card] [Versions de l'API](https://docs.whop.com/fr/developer/api/versioning.md)
>
> Pourquoi l'en-tête `Api-Version-Date` est important et comment l'épingler.


## Related topics

- [Téléverser des fichiers](https://docs.whop.com/fr/developer/guides/upload-files.md)
- [API Fichiers](https://docs.whop.com/fr/api-reference/files/file.md)
- [Gérer un programme de bounties](https://docs.whop.com/fr/developer/bounties/run-a-bounty-program.md)
