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

> Téléversez des fichiers via l'API avec une URL présignée, puis associez-les à des ressources Whop.

Téléversez des fichiers sur Whop pour les utiliser dans des cours, des forums, des profils, des litiges, et plus encore.

## Fonctionnement des téléversements

Le téléversement se déroule en deux étapes, et le SDK vous aide pour la première :

1. **Créez un enregistrement de fichier.** `files.create` renvoie l'`id` du nouveau fichier ainsi qu'une `upload_url` présignée et les `upload_headers` à envoyer avec.
2. **Envoyez vous-même les octets.** Effectuez un `PUT` du contenu du fichier vers `upload_url` avec ces en-têtes. Le SDK ne transfère pas les octets à votre place.

Une fois les octets reçus, le fichier est traité et son `upload_status` passe à `ready`. Utilisez `files.retrieve` pour interroger le fichier jusqu'à ce qu'il soit `ready`, puis associez l'`id` à une ressource et lisez l'`url` finale.

Pour téléverser directement depuis le navigateur afin que les octets ne transitent jamais par votre serveur, ou pour envoyer un fichier volumineux en plusieurs parties, consultez [Téléverser des fichiers directement](https://docs.whop.com/fr/developer/guides/direct-file-uploads.md).

## Initialiser le SDK

```typescript TypeScript theme={null}
import { WhopClient } from "@whop/sdk";

const client = new WhopClient({
  token: process.env.WHOP_API_KEY,
});
```

```python Python theme={null}
import os
from whop_sdk import Whop

client = Whop(
    token=os.environ["WHOP_API_KEY"],
)
```

```ruby Ruby theme={null}
require "whop_sdk"

client = Whop_sdk::Client.new(
  token: ENV.fetch("WHOP_API_KEY"),
)
```

```go Go theme={null}
import (
  "context"
  "os"

  whopsdk "github.com/whopio/whopsdk-go/v2"
  whopclient "github.com/whopio/whopsdk-go/v2/client"
  "github.com/whopio/whopsdk-go/v2/option"
)

client := whopclient.NewWhop(
  option.WithToken(os.Getenv("WHOP_API_KEY")),
)
```

```rust Rust theme={null}
use whop_sdk::prelude::*;

let config = ClientConfig {
    token: Some(std::env::var("WHOP_API_KEY").expect("WHOP_API_KEY is not set")),
    ..Default::default()
};
let client = Whop::new(config).expect("Failed to build client");
```

## Téléverser un fichier

Créez l'enregistrement, puis effectuez un `PUT` des octets vers l'URL présignée renvoyée.

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

// 1. Create the file record and get a presigned upload URL
const file = await client.files.create({ filename: "photo.jpg" });

// 2. Send the bytes to storage yourself
const bytes = await readFile("./photo.jpg");
await fetch(file.upload_url!, {
  method: "PUT",
  headers: file.upload_headers as Record<string, string>,
  body: bytes,
});

console.log(file.id); // file_xxxxxxxxxxxxx — attach it once it's ready
```

```python Python theme={null}
import requests

# 1. Create the file record and get a presigned upload URL
file = client.files.create(filename="photo.jpg")

# 2. Send the bytes to storage yourself
with open("./photo.jpg", "rb") as contents:
    requests.put(
        file.upload_url,
        headers=file.upload_headers or {},
        data=contents,
    )

print(file.id)  # file_xxxxxxxxxxxxx — attach it once it's ready
```

```ruby Ruby theme={null}
require "net/http"

# 1. Create the file record and get a presigned upload URL
file = client.files.create(filename: "photo.jpg")

# 2. Send the bytes to storage yourself
uri = URI(file.upload_url)
request = Net::HTTP::Put.new(uri)
(file.upload_headers || {}).each { |key, value| request[key] = value }
request.body = File.binread("./photo.jpg")
Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

puts file.id # file_xxxxxxxxxxxxx — attach it once it's ready
```

```go Go theme={null}
import (
  "bytes"
  "fmt"
  "net/http"
  "os"
)

// 1. Create the file record and get a presigned upload URL
file, err := client.Files.Create(context.TODO(), &whopsdk.CreateFilesRequest{
  Filename: "photo.jpg",
})
if err != nil {
  return err
}

// 2. Send the bytes to storage yourself
data, err := os.ReadFile("./photo.jpg")
if err != nil {
  return err
}
request, err := http.NewRequest(http.MethodPut, *file.UploadURL, bytes.NewReader(data))
if err != nil {
  return err
}
for key, value := range file.UploadHeaders {
  request.Header.Set(key, fmt.Sprint(value))
}
if _, err := http.DefaultClient.Do(request); err != nil {
  return err
}

fmt.Println(file.ID) // file_xxxxxxxxxxxxx — attach it once it's ready
```

```rust Rust theme={null}
// 1. Create the file record and get a presigned upload URL
let file = client
    .files
    .create(
        &CreateFilesRequest {
            filename: "photo.jpg".to_string(),
            ..Default::default()
        },
        None,
    )
    .await?;

// 2. Send the bytes to storage yourself
let contents = std::fs::read("./photo.jpg")?;
let mut request = reqwest::Client::new()
    .put(file.upload_url.as_deref().unwrap())
    .body(contents);
if let Some(headers) = &file.upload_headers {
    for (key, value) in headers {
        if let Some(value) = value.as_str() {
            request = request.header(key, value);
        }
    }
}
request.send().await?;

println!("{}", file.id); // file_xxxxxxxxxxxxx — attach it once it's ready
```

## Fichiers publics et privés

Chaque fichier que vous téléversez possède une **visibilité** qui contrôle son accès. Vous choisissez la visibilité au moment du téléversement et ne pouvez pas la modifier ensuite.

| Visibilité | Type d'URL | Qui peut y accéder | À utiliser pour |
| - | - | - | - |
| `private` (par défaut) | URL signée qui expire | Uniquement votre application, via l'API | Pièces jointes de messages, documents téléversés par les utilisateurs, contenus sensibles, fichiers générés par IA |
| `public` | URL permanente et non signée du réseau de diffusion de contenu | Toute personne disposant du lien | Images de produits, miniatures, éléments de marque, ressources marketing |

> [!WARNING]
>
> **Définissez la visibilité avant de téléverser.** Les fichiers publics sont mis en cache sur le CDN de Whop et accessibles à toute personne disposant de l'URL — il est impossible de révoquer l'accès. Si le contenu est propre à un utilisateur ou sensible, conservez la valeur par défaut `private`.

### Téléverser un fichier public

Transmettez une visibilité `public` lors de la création du fichier, puis téléversez les octets de la même manière :

```typescript TypeScript theme={null}
const file = await client.files.create({
  filename: "product-cover.jpg",
  visibility: "public",
});

// PUT the bytes to file.upload_url, then file.url is a permanent CDN URL
```

```python Python theme={null}
file = client.files.create(
    filename="product-cover.jpg",
    visibility="public",
)

# PUT the bytes to file.upload_url, then file.url is a permanent CDN URL
```

```ruby Ruby theme={null}
file = client.files.create(
  filename: "product-cover.jpg",
  visibility: "public",
)

# PUT the bytes to file.upload_url, then file.url is a permanent CDN URL
```

```go Go theme={null}
file, err := client.Files.Create(context.TODO(), &whopsdk.CreateFilesRequest{
  Filename:   "product-cover.jpg",
  Visibility: whopsdk.CreateFilesRequestVisibilityPublic.Ptr(),
})

// PUT the bytes to file.UploadURL, then file.URL is a permanent CDN URL
```

```rust Rust theme={null}
let file = client
    .files
    .create(
        &CreateFilesRequest {
            filename: "product-cover.jpg".to_string(),
            visibility: Some(CreateFilesRequestVisibility::Public),
            ..Default::default()
        },
        None,
    )
    .await?;

// PUT the bytes to file.upload_url, then file.url is a permanent CDN URL
```

Associer un fichier à une ressource le déplace vers le stockage correspondant à la visibilité de cette ressource. Une `visibility` explicite compte surtout pour les fichiers vers lesquels vous créez un lien direct sans les associer.

### Confirmer la fin du téléversement

Une fois les octets reçus, le fichier est traité de manière asynchrone. Récupérez-le jusqu'à ce que `upload_status` quitte `pending` et `processing`. Lorsqu'il vaut `ready`, lisez l'`url` finale. Lorsqu'il vaut `failed`, arrêtez-vous et remontez l'erreur.

```typescript TypeScript theme={null}
let uploaded = await client.files.retrieve({ id: file.id });

while (uploaded.upload_status === "pending" || uploaded.upload_status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  uploaded = await client.files.retrieve({ id: file.id });
}

if (uploaded.upload_status !== "ready") {
  throw new Error(`Upload failed: ${uploaded.upload_status}`);
}

console.log(uploaded.url);
```

```python Python theme={null}
import time

uploaded = client.files.retrieve(file.id)

while uploaded.upload_status in ("pending", "processing"):
    time.sleep(1)
    uploaded = client.files.retrieve(file.id)

if uploaded.upload_status != "ready":
    raise RuntimeError(f"Upload failed: {uploaded.upload_status}")

print(uploaded.url)
```

```ruby Ruby theme={null}
uploaded = client.files.retrieve(id: file.id)

while %w[pending processing].include?(uploaded.upload_status)
  sleep 1
  uploaded = client.files.retrieve(id: file.id)
end

raise "Upload failed: #{uploaded.upload_status}" unless uploaded.upload_status == "ready"

puts uploaded.url
```

```go Go theme={null}
import "time"

uploaded, err := client.Files.Retrieve(context.TODO(), &whopsdk.RetrieveFilesRequest{ID: file.ID})
if err != nil {
  return err
}

for uploaded.UploadStatus == whopsdk.FileUploadStatusPending ||
  uploaded.UploadStatus == whopsdk.FileUploadStatusProcessing {
  time.Sleep(time.Second)
  uploaded, err = client.Files.Retrieve(context.TODO(), &whopsdk.RetrieveFilesRequest{ID: file.ID})
  if err != nil {
    return err
  }
}

if uploaded.UploadStatus != whopsdk.FileUploadStatusReady {
  return fmt.Errorf("upload failed: %s", uploaded.UploadStatus)
}

fmt.Println(*uploaded.URL)
```

```rust Rust theme={null}
let mut uploaded = client.files.retrieve(&file.id, None).await?;

while matches!(
    uploaded.upload_status,
    FileUploadStatus::Pending | FileUploadStatus::Processing
) {
    tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    uploaded = client.files.retrieve(&file.id, None).await?;
}

if !matches!(uploaded.upload_status, FileUploadStatus::Ready) {
    panic!("upload failed: {}", uploaded.upload_status);
}

println!("{}", uploaded.url.unwrap());
```

### Accéder aux fichiers privés

Les URL des fichiers privés expirent. Pour obtenir une nouvelle URL, récupérez à nouveau le fichier par son ID :

```typescript TypeScript theme={null}
const file = await client.files.retrieve({ id: "file_xxxxxxxxxxxxx" });
console.log(file.url); // fresh signed URL
```

```python Python theme={null}
file = client.files.retrieve("file_xxxxxxxxxxxxx")
print(file.url)  # fresh signed URL
```

```ruby Ruby theme={null}
file = client.files.retrieve(id: "file_xxxxxxxxxxxxx")
puts file.url # fresh signed URL
```

```go Go theme={null}
file, err := client.Files.Retrieve(context.TODO(), &whopsdk.RetrieveFilesRequest{
  ID: "file_xxxxxxxxxxxxx",
})
fmt.Println(*file.URL) // fresh signed URL
```

```rust Rust theme={null}
let file = client
    .files
    .retrieve(&"file_xxxxxxxxxxxxx".to_string(), None)
    .await?;
println!("{}", file.url.unwrap()); // fresh signed URL
```

## Utiliser les fichiers téléversés

Une fois le fichier `ready`, transmettez son `id` dans tout appel API acceptant des pièces jointes :

```typescript TypeScript theme={null}
await client.courses.update({
  id: "course_xxxxxxxxxxxxx",
  thumbnail: { id: file.id },
});
```

```python Python theme={null}
client.courses.update(
    "course_xxxxxxxxxxxxx",
    thumbnail={"id": file.id},
)
```

```ruby Ruby theme={null}
client.courses.update(
  id: "course_xxxxxxxxxxxxx",
  thumbnail: { id: file.id },
)
```

```go Go theme={null}
client.Courses.Update(context.TODO(), &whopsdk.UpdateCoursesRequest{
  ID:        "course_xxxxxxxxxxxxx",
  Thumbnail: &whopsdk.UpdateCoursesRequestThumbnail{ID: file.ID},
})
```

```rust Rust theme={null}
client
    .courses
    .update(
        &"course_xxxxxxxxxxxxx".to_string(),
        &UpdateCoursesRequest {
            thumbnail: Some(UpdateCoursesRequestThumbnail { id: file.id }),
            ..Default::default()
        },
        None,
    )
    .await?;
```

## Propriétés des fichiers

| Propriété | Description |
| - | - |
| `id` | Identifiant unique (par exemple `file_xxxxxxxxxxxxx`) |
| `filename` | Nom de fichier d'origine |
| `content_type` | Type de média (par exemple `image/jpeg`), déduit de l'extension du nom de fichier |
| `size` | Taille du fichier en octets. `null` jusqu'à la fin du téléversement |
| `url` | Emplacement de téléchargement du fichier : une URL permanente du réseau de diffusion de contenu s'il est public, une URL signée qui expire s'il est privé. `null` jusqu'à la fin du téléversement |
| `upload_status` | Statut : `pending`, `processing`, `ready` ou `failed` |
| `visibility` | `public` ou `private` |
| `upload_url` | Une URL présignée vers laquelle effectuer le `PUT` des octets. Présente uniquement dans la réponse de `create` |
| `upload_headers` | En-têtes à envoyer avec le `PUT` de téléversement. Présents uniquement dans la réponse de `create` |


## Related topics

- [Téléverser des fichiers directement](https://docs.whop.com/fr/developer/guides/direct-file-uploads.md)
- [Gérer un programme de bounties](https://docs.whop.com/fr/developer/bounties/run-a-bounty-program.md)
- [API Chat](https://docs.whop.com/fr/developer/guides/chat.md)
