PeakMV

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

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)

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.

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)

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:

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:

{ "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

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:

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

Any client that takes a JSON config:

{ "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