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)
- 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.
- You cannot add credits. If the balance is too low, give the user the top-up link: https://peakmv.com/credits.
- Always send a
requestKey(any unique string) when creating an ad and reuse the same one when retrying. The same key never charges twice. - 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.
- 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. - 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
- 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. GET /api/ads/pricing(no key needed) to read prices, styles and limits.GET /api/ads/accountto check the credit balance.- For a software product,
POST /api/ads/analyze-urlwith the website address. It is free and returns the product name, key facts, a suggested style, five ad angles and animageUrl(the site's share image, already stored). - 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 returnedimageUrl. POST /api/ads/generatewith the images and choices. It returns at once with an ad id.GET /api/ads/{id}every 20 to 30 seconds untilsummary.statusisready(orfailed). Then usesummary.videoUrl(video ads) orsummary.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:
mode:video(default) orphoto.photomakes four still concepts for $2 and needs noseconds.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) or16:9(YouTube, web).1:1is also accepted.style: one ofhype,ugc,luxury,meme,clean,unboxing(below).captionStyle(video only, optional): burned-in caption look, one ofclassic,helvetica,box,serif,serif-box,none(defaultclassic;noneturns captions off).category:software(default; images are screenshots, shown on a screen in the scene) orproduct(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:
{ "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:
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
- Ask the user for the product website and which length and style they want (default: 12 seconds,
ugc,9:16). analyze_websitethen show the user the five angles and let them pick one.get_pricingandcheck_account. Tell the user: "This 12 second video costs $5. Your balance is $X. Go ahead?"create_adwith the chosen angle's hook,descriptionfrom the analysis, theimageUrlfrom the analysis and any extra screenshots the user gave you.- Poll
get_aduntilready. Give the uservideoUrlandpage.
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.