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

# Ads API 개요

> 크리에이티브를 생성한 다음 캠페인, 광고 그룹, 광고를 한 번의 요청으로 생성해 API로 Whop Ads를 시작하세요.

Whop Ads는 Whop 계정에서 바로 외부 광고 네트워크에 유료 광고를 게재합니다. 광고 지출은 모든 캠페인에 걸쳐 계정에 설정된 카드 또는 잔액으로 청구됩니다. 광고 계정, 검토, 게재 시작, 청구는 Whop이 처리합니다.

두 번의 API 호출만으로 아무것도 없는 상태에서 라이브 광고까지 만들 수 있습니다. 크리에이티브를 생성한 다음, 캠페인, 광고 그룹, 광고를 한 번의 요청으로 생성하세요.

## 리소스

| 리소스 | 용도 |
| - | - |
| [광고 캠페인](https://docs.whop.com/ko/api-reference/ad-campaigns/ad-campaign) | 최상위 컨테이너: 목표와 (선택적으로) 예산. |
| [광고 그룹](https://docs.whop.com/ko/api-reference/ad-groups/ad-group) | 광고 묶음에 대한 타기팅과 예산. |
| [광고](https://docs.whop.com/ko/api-reference/ads/ad) | 크리에이티브 단위 — 문구, 에셋, 도착 URL. |
| [오디언스](https://docs.whop.com/ko/api-reference/audiences/audience) | 광고 그룹에서 타기팅하거나 제외할 맞춤 오디언스. |

## 청구 및 결제 복구

지출은 캠페인 전체에 걸쳐 계정 수준에서 수금됩니다. 결제가 실패하면 각 캠페인에 설정된 active/paused `status`는 유지되지만 `delivery_status: "payment_failed"`로 게재가 차단됩니다. 계정의 결제 수단을 수정한 다음, 계정에 대해 [실패한 광고 결제 재시도](https://docs.whop.com/ko/api-reference/accounts/retry-failed-ads-payments.md)를 한 번 호출하세요. 응답은 백그라운드 시도를 대기열에 넣을 뿐이며 결제를 확정하지는 않습니다. 정산이 완료되면 다른 게재 요건을 충족하는 한 활성 캠페인은 재개될 수 있고 일시 중지된 캠페인은 일시 중지 상태로 유지됩니다.

대시보드 흐름, 요청 예시, 중복 요청 동작, 레거시 캠페인 처리 방식은 [광고 비용 결제](https://docs.whop.com/ko/developer/ads/overview.md#paying-for-ads)를 참고하세요.

## 최초 1회 설정

* **스코프**: `media:generate`, `media:read`, `ad_campaign:create`, `ad_campaign:update`, `ad_campaign:basic:read`.
* **광고 결제 수단**: 대시보드에서 연결합니다(잔액 또는 카드). 게재를 시작할 때만 필요하며, 초안은 결제 수단 없이도 작동합니다.

**1. 크리에이티브 생성**

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

잔액에서 청구됩니다(`amount_charged`, 잔액이 부족하면 `deposit_url`과 함께 `402` 반환). `status`가 `ready`가 될 때까지 [`GET /media/{id}`](https://docs.whop.com/ko/api-reference/media/retrieve-media-asset)를 폴링한 다음 `file.id`를 사용하세요.

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

`failed`이면 요금이 환불됩니다. 프롬프트를 수정해 다시 시도하세요. 동영상: `"type": "video"`와 함께 선택적으로 `duration_seconds`(5/10/15), `resolution`(`480p`–`4k`), 최대 4개의 `reference_media` 파일 ID(첫 번째 파일이 시작 프레임의 기반이 됨)를 지정합니다.

**2. 광고 생성 및 게재 시작 — 한 번의 요청**

인라인 `ad_group`과 `ad_campaign`을 포함한 [`POST /ads`](https://docs.whop.com/ko/api-reference/ads/create-an-ad)는 하나의 트랜잭션으로 전체 트리를 생성하고 게재를 시작합니다.

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

아직 지출할 준비가 되지 않았나요? `ad_campaign`에 `"status": "draft"`를 추가한 다음, 나중에 [`PATCH /ad_campaigns/{id}`](https://docs.whop.com/ko/api-reference/ad-campaigns/update-an-ad-campaign) `{"status": "active"}`로 게재를 시작하세요.

| 필드 | 규칙 |
| - | - |
| `creatives` | `format`이 없는 항목(기본 에셋) 하나가 필요합니다. `square` / `vertical` / `horizontal`은 그 위에 추가하는 선택적 크롭입니다. |
| `url` | 웹사이트 광고에 필요합니다. whop.com 스토어 페이지는 그대로 사용할 수 있으며, 외부 페이지에는 [Whop 픽셀](https://docs.whop.com/ko/developer/ads/pixel.md)이 설치되어 있어야 합니다. |
| 예산 | 한 수준에서만 예산을 소유합니다. 광고 그룹의 `budget_amount`(기본값) 또는 `budget_optimization: "ad_campaign"`을 사용한 캠페인의 `budget_amount` 중 하나이며, 둘 다 사용할 수는 없습니다. |
| 통화 | `budget_amount`는 예산이 저장되고 청구되는 통화인 USD입니다. 대신 계정의 `ads_reporting_currency`로 예산을 지정하려면 `budget_amount_local`을 보내세요. Whop이 현재 환율로 변환해 USD 결과를 저장합니다. 둘 중 하나만 보내고, 둘 다 보내지 마세요. 응답에는 `budget_amount`, `budget_amount_local`, `budget_currency`가 포함됩니다. |
| 타기팅 | 자동 최적화를 원하면 `demographics` / `devices`를 생략하세요. `regions`는 ISO 3166(`"US"`, `"US-CA"`)을 사용합니다. |

기존 컨테이너를 재사용하려면 `ad_group` 대신 `ad_group_id`를, `ad_campaign` 대신 `ad_campaign_id`를 전달하세요.

**3. 모니터링**

[`GET /ads/{id}`](https://docs.whop.com/ko/api-reference/ads/retrieve-an-ad)를 폴링하세요. `delivery_status`는 실시간 상태이며(콘텐츠 검토를 위한 짧은 `in_review`는 정상입니다), `issues[]`에는 광고 네트워크가 비동기적으로 거부한 항목에 대해 사람이 읽을 수 있는 `message`가 담겨 있습니다.

광고, 광고 그룹 또는 캠페인에서 [`pause`](https://docs.whop.com/ko/api-reference/ads/pause-an-ad) / [`unpause`](https://docs.whop.com/ko/api-reference/ads/unpause-an-ad)로 게재를 제어하세요. 문구나 크리에이티브는 [`PATCH /ads/{id}`](https://docs.whop.com/ko/api-reference/ads/update-an-ad)로 편집하세요. `creatives`를 보내면 전체 세트가 교체되므로 기본 항목을 포함해야 합니다.

## 오류

모든 검증 실패는 무엇을 수정해야 하는지 알려주는 메시지와 함께 `400`을 반환합니다.

| 오류에 포함된 내용 | 해결 방법 |
| - | - |
| `The Whop pixel was not detected on <url>` | 자체 whop.com 스토어 페이지를 사용하거나 랜딩 페이지에 [픽셀을 설치](https://docs.whop.com/ko/developer/ads/pixel.md)하세요. |
| `Connect an ads payment method before launching` | `ad_campaign.status: "draft"`로 생성하고, 사용자가 대시보드에서 결제 수단을 연결하게 한 다음, `PATCH`로 `active`로 변경하세요. |
| `Include a base creative` | `format`이 없는 `creatives` 항목을 추가하세요. |
| `A destination URL is required` | `url`을 전달하세요. |
| `budget_amount is required` / `can't be set` | 예산을 올바른 수준으로 옮기세요(앞의 필드 규칙 참고). |
| `Provide either budget_amount (USD) or budget_amount_local` | 두 필드가 서로 다른 예산을 지정했습니다. 하나만 보내세요. 로컬 금액이 저장된 금액을 그대로 반영하는, 그대로 되돌려 보낸 `GET` 본문은 괜찮습니다. |
| `503` `Exchange rate for <currency> is unavailable` | 현재 Whop에 계정 보고 통화의 최신 환율이 없습니다. 몇 분 후 다시 시도하세요. |
| `402` + `deposit_url` (미디어) | 사용자를 `deposit_url`로 보내 잔액을 충전하게 한 다음 다시 시도하세요. |


## Related topics

- [Whop Ads로 광고하기](https://docs.whop.com/ko/developer/ads/overview.md)
- [Ads API](https://docs.whop.com/ko/api-reference/ads/ad.md)
- [Whop API 개요](https://docs.whop.com/ko/api-reference/overview.md)
