# AdsCreator for agents

AdsCreator makes on-brand image and video ads from a website. This file tells you, an AI agent, how to connect and make ads for your user.

## Connect

Two URLs, same server and tools (MCP, Streamable HTTP):

- https://www.adscreator.com/mcp: for agents that keep their own config (Claude Code, Cursor, Codex, custom agents). No auth needed to start: you can create the account yourself (below). After that send `Authorization: Bearer <API key>`. Keys start with `ac_sk_`. If you cannot set headers, pass the key as the `apiKey` argument on every tool call.
- https://www.adscreator.com/mcp/oauth: for chat apps (Claude, ChatGPT) that cannot keep a key between conversations. Sign-in is required: the app opens the AdsCreator sign-in when you connect. There is no email-code step, and `create_account`/`verify_account` are not offered there. API keys also work on this URL.

## Create the account (no key yet, on https://www.adscreator.com/mcp)

1. Ask your user for their email. Call `create_account` with `{ "email": "…" }`. A 6-digit code is emailed to them.
2. Ask your user for the code. Call `verify_account` with `{ "email": "…", "code": "…" }`.
3. You get `{ "apiKey": "ac_sk_…", "credits": 5, "trialCreditsGranted": 5, … }`. Keep the key for this session. Do not print it back to the user unless they ask.

A wrong code: check it with the user and retry. An expired code, or one locked after too many tries: call `create_account` again for a new code.

New accounts get 5 free credits once, no card. Signed in with OAuth instead? `get_account` adds them on a new account's first check.

## Happy path

1. `import_brand` with the user's website URL (free). Returns a brand id. `list_brands` finds brands already imported.
2. `create_image_ads` with that brand id. Returns a job id.
3. `wait_for_job` with the job id. Returns the finished ads with links. Call it again while `done` is false.
4. Show the user the ads. Ask what to change, then `edit_image_ad`, `resize_image_ad` or make more.

Videos: pick a format with `list_video_formats`, then `create_video_ad`, then `wait_for_job` with the `videoAdId` (videos take minutes). Animated stories and song ads need `plan_story_video` first; creator (UGC) ads can take a script from `write_ugc_script`. Both are free.

Other tools: `get_brand`, `list_products`, `list_image_ads`, `list_videos`, `get_video`, `get_job`, `get_usage`. List the server's tools for exact arguments.

## Costs

- Image ad: 1 credit per image (count × sizes). Edit: 1 credit. Resize: 1 credit per new size.
- Brand import, scripts and story plans: free.
- Failed images and videos are refunded automatically.

| Video format | Name | Credits by length | Typical wait | Steps |
|---|---|---|---|---|
| `motion_graphics` | Motion graphics | 15s = 16, 20s = 16, 25s = 24, 30s = 24 | ~13 min | create_video_ad (direction = creative brief) → wait_for_job with videoAdId |
| `ugc_talking` | UGC talking ad | 15s = 10, 30s = 15 | ~6 min | write_ugc_script (free, optional; show it to the user) → create_video_ad with ugcScript → wait_for_job with videoAdId |
| `pixar_story` | Animated story | 30s = 24, 40s = 32, 45s = 40, 50s = 40, 60s = 48 | ~20 min | plan_story_video (free; show the proposal to the user) → create_video_ad with storyProposal → wait_for_job with videoAdId |
| `funny_musical` | Animated song ad | 35s = 32, 45s = 40, 60s = 48 | ~20 min | plan_story_video (free; show the proposal to the user) → create_video_ad with storyProposal → wait_for_job with videoAdId |
| `story_ad` | Story ad | 60s = 48, 90s = 72, 120s = 96, 180s = 144 | ~20 min | create_video_ad (direction = story direction, optional) → wait_for_job with videoAdId |
| `launch_video` | Launch video | 20s = 24, 30s = 32, 45s = 48 | ~35 min | create_video_ad (direction = what to launch and the key message) → wait_for_job with videoAdId |

`get_pricing` returns all of this. Tell the user what a request will cost before you spend more than a few credits.

## More credits

When a tool says `insufficient_credits`, call `list_credit_packs`, then `buy_credits` with a `packId`. It returns a Stripe `checkoutUrl`. Give the link to your user; they pay, the credits land on the account (`get_account` confirms). Never try to pay yourself.

| packId | Pack | Credits | Price |
|---|---|---|---|
| `pack_v2_25` | Top-up | 25 | $20 |
| `pack_v2_60` | Small | 60 | $42 |
| `pack_v2_120` | Medium | 120 | $72 |
| `pack_v2_300` | Large | 300 | $150 |
| `pack_v2_750` | Bulk | 750 | $310 |

## REST fallback

```
POST https://www.adscreator.com/api/agent-accounts         { "email": "…" }
POST https://www.adscreator.com/api/agent-accounts/verify  { "email": "…", "code": "…" }  → { "apiKey": "ac_sk_…", "credits": 5, … }
GET  https://www.adscreator.com/api/credits/purchase          → { "packs": [{ "id", "credits", "priceUsd" }] }
POST https://www.adscreator.com/api/credits/purchase          { "packId": "…" }  → { "checkoutUrl": "…" }  (Authorization: Bearer <key>)
POST https://www.adscreator.com/api/agent-accounts/trial    → { "trialCreditsGranted", "credits" }  (Authorization: Bearer <key or OAuth token>; once per account)
```

Sign-up and purchase errors are `{ "error", "code", "fix" }`; out of credits on any paid route is HTTP 402 with `required` and `balance`.

Full API: https://www.adscreator.com/openapi.json and https://www.adscreator.com/developers. Humans: https://www.adscreator.com/agents. Site map: https://www.adscreator.com/llms.txt.
