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

# Vue d'ensemble de l'API Ads

> Lancez des Whop Ads via l'API en générant une création, puis en créant la campagne, le groupe d'annonces et l'annonce en une seule requête.

Whop Ads diffuse des publicités payantes sur des réseaux publicitaires externes directement depuis votre compte Whop. Les dépenses publicitaires sont facturées sur la carte ou le solde configuré du compte, pour l'ensemble de ses campagnes. Whop gère le compte publicitaire, la vérification, le lancement et la facturation.

Deux appels API suffisent pour passer de rien à une annonce en ligne : générer une création, puis créer la campagne, le groupe d'annonces et l'annonce en une seule requête.

## Ressources

| Ressource | Objectif |
| - | - |
| [Ad Campaign](https://docs.whop.com/fr/api-reference/ad-campaigns/ad-campaign) | Conteneur de premier niveau : objectif et (éventuellement) budget. |
| [Ad Group](https://docs.whop.com/fr/api-reference/ad-groups/ad-group) | Ciblage et budget d'un ensemble d'annonces. |
| [Ad](https://docs.whop.com/fr/api-reference/ads/ad) | L'unité créative : texte, ressources, URL de destination. |
| [Audience](https://docs.whop.com/fr/api-reference/audiences/audience) | Une audience personnalisée à cibler ou à exclure dans les groupes d'annonces. |

## Facturation et recouvrement des paiements

Les dépenses sont prélevées au niveau du compte, pour l'ensemble des campagnes. Un paiement échoué bloque la diffusion avec `delivery_status: "payment_failed"` tout en conservant le `status` actif/en pause configuré de chaque campagne. Corrigez le moyen de paiement du compte, puis appelez [Retry Failed Ads Payments](https://docs.whop.com/fr/api-reference/accounts/retry-failed-ads-payments.md) une seule fois pour le compte. La réponse met en file d'attente une tentative en arrière-plan ; elle ne confirme pas le paiement. Après le règlement, les campagnes actives peuvent reprendre et les campagnes en pause restent en pause, sous réserve des autres conditions de diffusion.

Consultez [Payer les publicités](https://docs.whop.com/fr/developer/ads/overview.md#paying-for-ads) pour le parcours dans le tableau de bord, un exemple de requête, le comportement en cas de requête en double et la gestion des anciennes campagnes.

## Configuration initiale

* **Scopes** : `media:generate`, `media:read`, `ad_campaign:create`, `ad_campaign:update`, `ad_campaign:basic:read`.
* **Moyen de paiement publicitaire** : connecté dans le tableau de bord (solde ou carte). Seul le lancement en a besoin ; les brouillons fonctionnent sans.

**1. Générer une création**

```bash theme={null}
curl -X POST "https://api.whop.com/api/v1/media/generate" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "image", "prompt": "A running club jogging across a bridge at sunrise, warm light, joyful energy"}'
```

Facturé sur votre solde (`amount_charged` ; solde insuffisant → `402` avec une `deposit_url`). Interrogez [`GET /media/{id}`](https://docs.whop.com/fr/api-reference/media/retrieve-media-asset) jusqu'à ce que `status` soit `ready`, puis utilisez `file.id` :

```json theme={null}
{
	"id": "media_Hx7qg4tZc97o",
	"status": "ready",
	"file": { "id": "file_Zsv4DYkrbWE7h" }
}
```

`failed` rembourse le montant prélevé : ajustez le prompt et réessayez. Vidéo : `"type": "video"` plus, en option, `duration_seconds` (5/10/15), `resolution` (`480p`–`4k`) et jusqu'à 4 ID de fichiers `reference_media` (le premier sert de base à l'image d'ouverture).

**2. Créer et lancer l'annonce — une seule requête**

[`POST /ads`](https://docs.whop.com/fr/api-reference/ads/create-an-ad) avec un `ad_group` et un `ad_campaign` intégrés crée toute l'arborescence en une seule transaction et la lance :

```bash theme={null}
curl -X POST "https://api.whop.com/api/v1/ads" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Run club launch ad",
    "primary_texts": ["Join 10,000 runners chasing their next PR together."],
    "headlines": ["Find your stride"],
    "call_to_action": "sign_up",
    "url": "https://whop.com/your-store-page",
    "creatives": [{"id": "file_Zsv4DYkrbWE7h"}],
    "ad_group": {
      "title": "US broad",
      "budget_amount": 25,
      "budget_type": "daily",
      "regions": {"include": {"countries": ["US"]}},
      "ad_campaign": {"title": "Run club growth", "objective": "sales"}
    }
  }'
```

Pas encore prêt à dépenser ? Ajoutez `"status": "draft"` à `ad_campaign`, puis lancez plus tard avec [`PATCH /ad_campaigns/{id}`](https://docs.whop.com/fr/api-reference/ad-campaigns/update-an-ad-campaign) `{"status": "active"}`.

| Champ | Règle |
| - | - |
| `creatives` | Une entrée sans `format` est obligatoire (la ressource de base). `square` / `vertical` / `horizontal` sont des recadrages optionnels qui s'y ajoutent. |
| `url` | Obligatoire pour les annonces de site web. Votre page de boutique whop.com fonctionne telle quelle ; une page externe nécessite l'installation de votre [pixel Whop](https://docs.whop.com/fr/developer/ads/pixel.md). |
| Budget | Un seul niveau le détient : `budget_amount` sur le groupe d'annonces (par défaut), ou sur la campagne avec `budget_optimization: "ad_campaign"`, jamais les deux. |
| Devise | `budget_amount` est en USD, devise dans laquelle les budgets sont stockés et facturés. Pour exprimer un budget dans la `ads_reporting_currency` du compte à la place, envoyez `budget_amount_local` ; Whop le convertit au taux actuel et stocke le résultat en USD. Envoyez l'un ou l'autre, jamais les deux. Les réponses contiennent `budget_amount`, `budget_amount_local` et `budget_currency`. |
| Ciblage | Omettez `demographics` / `devices` pour une optimisation automatique. `regions` utilise la norme ISO 3166 (`"US"`, `"US-CA"`). |

Pour réutiliser des conteneurs existants, passez `ad_group_id` au lieu de `ad_group`, ou `ad_campaign_id` au lieu de `ad_campaign`.

**3. Surveiller**

Interrogez [`GET /ads/{id}`](https://docs.whop.com/fr/api-reference/ads/retrieve-an-ad) : `delivery_status` correspond à l'état en direct (un bref `in_review` pour la modération du contenu est normal), et `issues[]` contient un `message` lisible pour tout ce que le réseau publicitaire a rejeté de manière asynchrone.

Contrôlez la diffusion avec [`pause`](https://docs.whop.com/fr/api-reference/ads/pause-an-ad) / [`unpause`](https://docs.whop.com/fr/api-reference/ads/unpause-an-ad) sur les annonces, les groupes d'annonces ou les campagnes. Modifiez le texte ou les créations avec [`PATCH /ads/{id}`](https://docs.whop.com/fr/api-reference/ads/update-an-ad) : envoyer `creatives` remplace l'ensemble complet, incluez donc l'entrée de base.

## Erreurs

Chaque contrôle renvoie une erreur `400` dont le message indique ce qu'il faut corriger :

| L'erreur contient | Correction |
| - | - |
| `The Whop pixel was not detected on <url>` | Utilisez votre propre page de boutique whop.com, ou [installez le pixel](https://docs.whop.com/fr/developer/ads/pixel.md) sur la page de destination. |
| `Connect an ads payment method before launching` | Créez avec `ad_campaign.status: "draft"`, demandez à l'utilisateur de connecter un moyen de paiement dans le tableau de bord, puis faites un `PATCH` vers `active`. |
| `Include a base creative` | Ajoutez une entrée `creatives` sans `format`. |
| `A destination URL is required` | Passez `url`. |
| `budget_amount is required` / `can't be set` | Déplacez le budget au bon niveau (voir les règles de champs ci-dessus). |
| `Provide either budget_amount (USD) or budget_amount_local` | Les deux champs indiquaient des budgets différents ; envoyez-en un seul. Renvoyer le corps d'un `GET`, dont le montant local reprend le montant stocké, est accepté. |
| `503` `Exchange rate for <currency> is unavailable` | Whop ne dispose pas actuellement d'un taux récent pour la devise de reporting du compte ; réessayez dans quelques minutes. |
| `402` + `deposit_url` (media) | Redirigez l'utilisateur vers `deposit_url` pour recharger son solde, puis réessayez. |


## Related topics

- [Faire de la publicité avec Whop Ads](https://docs.whop.com/fr/developer/ads/overview.md)
- [Concepts clés de l'API Whop](https://docs.whop.com/fr/developer/concepts.md)
- [Démarrage rapide de l'API Whop](https://docs.whop.com/fr/developer/quickstart.md)
