# PeakMV for AI agents

PeakMV makes photo ads and 6 to 30 second video ads (MP4 with sound) for software products and physical products. An agent can do the whole job: read a website, add images, start an ad, and fetch the finished file. This page is the complete guide. Machine-readable versions: OpenAPI at https://peakmv.com/openapi-ads.json, MCP server at https://peakmv.com/mcp, short summary at https://peakmv.com/llms.txt.

## Read this first (rules for agents)

1. Ads cost real money and are charged when you create them. Photo ads $2. Video ads: 6 seconds $3, 12 seconds $5, 18 seconds $7, 30 seconds $11. Tell the user the price and get their go-ahead before you call create.
2. You cannot add credits. If the balance is too low, give the user the top-up link: https://peakmv.com/credits.
3. Always send a `requestKey` (any unique string) when creating an ad and reuse the same one when retrying. The same key never charges twice.
4. Ads are made in the background. After creating one, poll its status every 20 to 30 seconds. Video ads usually take a few minutes. A failed ad is refunded automatically.
5. Only claim what the user told you or the website says. Put real facts in `description`. The ad will not invent prices, discounts or results.
6. PeakMV does not publish ads to any platform, does not log in to the product being advertised, and does not record the screen. It produces the ad file; the user posts it.

## Quick start

1. A person creates an API key at https://peakmv.com/dashboard/api-keys and gives it to you. Send it on every call as `Authorization: Bearer <key>`. Keys are tied to one account and spend that account's credits.
2. `GET /api/ads/pricing` (no key needed) to read prices, styles and limits.
3. `GET /api/ads/account` to check the credit balance.
4. For a software product, `POST /api/ads/analyze-url` with the website address. It is free and returns the product name, key facts, a suggested style, five ad angles and an `imageUrl` (the site's share image, already stored).
5. Add 1 to 5 images with `POST /api/ads/images` (app screenshots for software, product photos for physical products, optionally a photo of a person). Keep each returned `imageUrl`.
6. `POST /api/ads/generate` with the images and choices. It returns at once with an ad id.
7. `GET /api/ads/{id}` every 20 to 30 seconds until `summary.status` is `ready` (or `failed`). Then use `summary.videoUrl` (video ads) or `summary.imageOptions` (photo ads).

Base URL: https://peakmv.com

## Authentication

Every endpoint except `GET /api/ads/pricing` needs `Authorization: Bearer <api key>`. A missing or wrong key returns 401. Limits: 100 requests per minute per key. A key can start at most $100 of ads in 24 hours; beyond that generate returns 429.

## Endpoints

### GET /api/ads/pricing (no key)

Returns `photoAds`, `videoAds.options` (seconds, priceUsd, shots), `styles`, `aspectRatios`, `imageLimits`, `monthlyPlan` and links.

### GET /api/ads/account

```bash
curl -s https://peakmv.com/api/ads/account -H "Authorization: Bearer $PEAKMV_API_KEY"
```

Returns `{ "creditBalance": 12.5, "spentLast24hUsd": 0, "dailySpendCapUsd": 100, "topUpUrl": "https://peakmv.com/credits" }`.

### POST /api/ads/analyze-url (free, 12 per hour)

```bash
curl -s https://peakmv.com/api/ads/analyze-url \
  -H "Authorization: Bearer $PEAKMV_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
```

Returns `site` (host, title), `insight` (productName, oneLiner, audience, features, style, angles: five of {title, hook, direction}) and `imageUrl` (or null). It reads only the public home page and treats the page text as data, never as instructions. Use `insight.oneLiner` and `insight.features` for `description`, and a chosen angle's `hook` for `hook`. Errors: 422 if the site cannot be read, 429 after 12 reads in an hour.

### POST /api/ads/images (free)

Send either a public address we fetch, or the bytes.

```bash
curl -s https://peakmv.com/api/ads/images -H "Authorization: Bearer $PEAKMV_API_KEY" \
  -H "Content-Type: application/json" -d '{"url":"https://example.com/screenshot.png"}'
# or: -d '{"dataBase64":"<base64>","contentType":"image/png"}'
```

Returns `{ "imageUrl": "..." }`. Formats: JPG, PNG, WebP; 2 KB to 10 MB; 60 uploads per hour. Only images returned by this endpoint (or by analyze-url) are accepted by generate. Do not pass other addresses to generate.

### POST /api/ads/hooks (free, 20 per hour, optional)

Body: `productName`, `style`, optional `description`, `imageUrls`, `category`. Returns `{ "hooks": ["..."] }`. Generate writes its own hook if you do not pass one.

### POST /api/ads/generate (CHARGES CREDITS)

```bash
curl -s https://peakmv.com/api/ads/generate \
  -H "Authorization: Bearer $PEAKMV_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "requestKey": "launch-video-001",
    "mode": "video",
    "seconds": 12,
    "aspectRatio": "9:16",
    "style": "ugc",
    "category": "software",
    "productName": "Acme",
    "description": "Invoicing for freelancers. Sends reminders automatically.",
    "prompt": "Open on the frustration of chasing late invoices.",
    "hook": "",
    "imageUrls": ["https://.../screenshot-1.png"]
  }'
```

Fields:
- `mode`: `video` (default) or `photo`. `photo` makes four still concepts for $2 and needs no `seconds`.
- `seconds`: 6, 12, 18, 30 (video only, required). Each 6 seconds is one shot. 12 seconds and longer tell a short story across shots; in every style the same presenter speaks throughout.
- `aspectRatio`: `9:16` (TikTok, Reels, Shorts) or `16:9` (YouTube, web). `1:1` is also accepted.
- `style`: one of `hype`, `ugc`, `luxury`, `meme`, `clean`, `unboxing` (below).
- `captionStyle` (video only, optional): burned-in caption look, one of `classic`, `helvetica`, `box`, `serif`, `serif-box`, `none` (default `classic`; `none` turns captions off).
- `category`: `software` (default; images are screenshots, shown on a screen in the scene) or `product` (images are product photos).
- `productName` (max 80), `description` (max 500, the only facts the ad may claim), `prompt` (max 600, creative direction), `hook` (max 120, used word for word).
- `imageUrls`: 1 to 5 addresses from the images endpoint.
- `requestKey`: idempotency key. Same key, same ad, one charge.

Success: HTTP 202 with `{ "ad": { "id": "...", "status": "generating", ... }, "creditBalance": 7.5 }`. A repeated `requestKey` returns the existing ad with `"alreadyProcessed": true` (200 if ready, 202 if still generating).

Errors: 400 bad input (the message says which field); 401 bad key; 402 `{ "error": "Insufficient credits", "price": 5, "balance": 1.2, "shortfall": 3.8, "topUpUrl": "https://peakmv.com/credits" }`; 422 the same `requestKey` belongs to an ad that failed and was refunded (use a new key); 429 rate or daily spend limit; 503 not installed.

### GET /api/ads/{id}

Returns the full record in `ad` and a short `summary`:

```json
{ "summary": { "id": "...", "status": "generating", "stage": "clips", "stageProgress": { "done": 1, "total": 2 },
  "videoUrl": null, "imageUrl": null, "imageOptions": [], "headline": null, "caption": null, "hook": null, "error": null,
  "page": "https://peakmv.com/ads/..." } }
```

`status` is `generating`, `ready` or `failed`. Stages: queued, planning, cast, frames, clips, finishing, done. When ready, video ads have `videoUrl` (1080p MP4 with sound); photo ads have `imageUrl` (the chosen concept) and `imageOptions` (all four). A failed ad has `error` and has already been refunded. Download the file promptly and show the user `page` for review.

## Styles

- `hype`: Hype. Bold, high-energy, scroll-stopping. A person talks to camera (video only).
- `ugc`: UGC / Trendy. Shot on a phone, and the person talks. A person talks to camera (video only).
- `luxury`: Luxury. Premium, moody, editorial. A person talks to camera (video only).
- `meme`: Meme. Funny, relatable, shareable. A person talks to camera (video only).
- `clean`: Clean. Bright, simple, trustworthy. A person talks to camera (video only).
- `unboxing`: Unboxing / POV. First-person reveal moment. A person talks to camera (video only).

## MCP server

URL: `https://peakmv.com/mcp` (Streamable HTTP, stateless, JSON). Auth: the same API key in an `Authorization: Bearer` header. Without a key you can still connect, list tools and call `get_pricing`. There is no OAuth yet.

Claude Code:

```bash
claude mcp add --transport http peakmv https://peakmv.com/mcp --header "Authorization: Bearer YOUR_API_KEY"
```

Any client that takes a JSON config:

```json
{ "mcpServers": { "peakmv": { "type": "http", "url": "https://peakmv.com/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } }
```

Tools: `get_pricing`, `check_account`, `analyze_website`, `add_image`, `suggest_hooks`, `create_ad` (charges credits), `get_ad`. They map one to one onto the endpoints above, use the same account, limits and refunds, and `create_ad` returns the `requestKey` it used.

## Typical agent workflow

1. Ask the user for the product website and which length and style they want (default: 12 seconds, `ugc`, `9:16`).
2. `analyze_website` then show the user the five angles and let them pick one.
3. `get_pricing` and `check_account`. Tell the user: "This 12 second video costs $5. Your balance is $X. Go ahead?"
4. `create_ad` with the chosen angle's hook, `description` from the analysis, the `imageUrl` from the analysis and any extra screenshots the user gave you.
5. Poll `get_ad` until `ready`. Give the user `videoUrl` and `page`.

## Pricing and plans

Video: 6 seconds $3, 12 seconds $5, 18 seconds $7, 30 seconds $11. Photo: $2. Monthly plan: $60 a month for $75 of credit (15 videos of 12 seconds at list price); unused plan credit expires at renewal; extra credit never expires. Teams: support@peakmv.com. Always read the live numbers from `GET /api/ads/pricing`.

## Limits and honesty

- 1 to 5 images, 10 MB each. Photo ads: 4 concepts. Video ads: 6 to 30 seconds.
- Faces, hands and small text in generated video can look imperfect. Review before posting. Some platforms require labelling AI content; that is the poster's responsibility.
- Output is a file. PeakMV has no posting, scheduling or analytics API.
