For AI agents: the complete documentation index is available at /docs/llms.txt. Markdown versions of these documentation pages are available by appending .md to the page URL or requesting Accept: text/markdown.

VidGuy Docs

Build videos faster with VidGuy

Guides and best practices for turning prompts into platform-ready videos.

Ads on Demand

Send one URL and get paid-social ads back. It can be an online store, a single product page, a service business's site, or an App Store / Google Play listing. VidGuy reads the page, finds the real products, prices, reviews and offers, and builds the ads from them. You don't need to set up a brand first.

Available on the Pro, Scale and pay-as-you-go Agent plans, through the API (POST /api/v1/snacks/on-demand) and the MCP tool generate_ads_from_url.

Ad types

static-ad

Two finished image ads in two different formats (review card, us-vs-them, benefit callouts and more), so you can A/B test them. Stores get the real product; service businesses a scene of the service with their real logo.

ugc-ad

A 9:16 creator video. The presenter wears, uses or holds the product, whichever fits it, and talks to camera.

greenscreen-ad

The presenter reacts in front of a scrolling phone screenshot of your product page and points at the price, rating or offer.

animated-ad

A ~30 s narrated animated story: claymation, 3D, felt or cartoon. The story comes first and the product shows up as the payoff.

music-ad

A ~30 s animated music video. A character sings an original song about a relatable moment, and the product arrives in the last chorus.

Any language

Pass a language code and every word on screen, in the script, the lyrics and the voice-over follows it.

A store gets 3 static-ad + 1 ugc-ad when you don't name any types (7 ads: 6 images and 1 video). A service business or an app gets 1 static-ad + 1 ugc-ad + 1 animated-ad (69 credits): its static ads show a scene of the service with the brand's real logo stamped in the corner. animated-ad, greenscreen-ad and music-ad only run when you ask for them.

Music ads

music-ad turns your product into a short animated music video:

  1. The agent picks the song and the look. It chooses a genre that suits the product and its audience, such as doo-wop for a vintage soda, stomp-folk for travel shoes or K-pop for skincare. It also picks an animation style, such as a 1930s rubber-hose cartoon, felt stop-motion or claymation.
  2. The story comes first. The first part of the song sets up a relatable moment with no product on screen. The product is revealed in the last section, and the brand name is sung in the hook.
  3. The character sings on camera. The song is generated first. Each ~10-second section is then animated with that part of the song, so the character's mouth follows the vocals. The full song plays over the final cut, with a hook caption and an end caption.

Want a specific genre, look or story? Say so in prompt, for example "moody late-night jazz club" or "surf rock, 80s cartoon", and the agent follows it.

Make a request

curl -X POST https://www.vidguy.ai/api/v1/snacks/on-demand \
  -H "Authorization: Bearer vf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "shopUrl": "https://drinkolipop.com/products/vintage-cola",
    "types": ["music-ad", "static-ad"],
    "prompt": "summer picnic vibe",
    "language": "en",
    "render": true
  }'

Reading the page takes 15–30 seconds before the 201 comes back, so give the request an HTTP timeout of at least 90 seconds (150 seconds when you ask for a greenscreen-ad, which also screenshots the whole page). The response has a jobId; poll GET /api/v1/jobs/{id} (see Polling). Most ads are ready in 1–3 minutes. With render: true, the finished PNG and MP4 files are listed in result.renderedAssets[].

FieldWhat it does
shopUrlThe store, product page, service site or app listing. Bare domains work.
typesWhich ads to make: static-ad, ugc-ad, greenscreen-ad, animated-ad, music-ad.
countNumber of ad slots (1–5); repeats the requested types.
promptA creative steer for every ad: theme, audience, angle, or a music-ad genre or look.
languageISO 639-1 code, e.g. es, de, fr, sq. Default en.
adAspectRatioFrame for static ads: 4:5 (default), 1:1 or 9:16. Video ads are always 9:16.
adFormatsPin the static-ad layouts, e.g. ["review_card", "us_vs_them"].
animationStyleLook for animated-ad: claymation, pixar_3d, felt_stop_motion or cartoon_2d. The agent picks one if you leave it out.
presenterImageUrlA photo of the person to feature instead of a stock presenter. See "Your own presenter" below.
excludeAd types to leave out of the default pack.
nameA name for the job.
callbackUrlA URL we call when the job finishes.
renderAlso render the files server-side (+1 credit).

Your own presenter

Want your influencer, founder or mascot in the ads instead of a stock presenter? Pass a public image URL in presenterImageUrl.

  • ugc-ad and greenscreen-ad: they're the one on camera with your product, and the voice matches their gender and age.
  • static-ad: the agent decides how to use them in each ad, like holding or wearing the product in a lifestyle shot. Text-heavy layouts may leave them out.
  • animated-ad and music-ad: they become the hero or the singer, drawn in the film's style so you can still tell it's them.

Send one clear, well-lit photo of one person. JPEG, PNG or WebP, up to 15 MB, at least 256 px on the short side (1024 px or more looks best). A bad URL fails right away with a 400 and costs nothing. Using a presenter costs nothing extra.

We check the photo before making the ads. If it doesn't show a person (say it's a product shot), we skip the ugc-ad and greenscreen-ad instead of using a stranger, and the other ads run without a presenter. Every image of the presenter is checked against your photo and regenerated once if the face doesn't match. Only send photos of people who agreed to appear in your ads.

What stays true

Every number, price, rating, review quote, discount code and press mention in an ad comes from the page. Reviews have to appear word for word on the page, or we drop them. Presenters never claim they've used the product themselves. Ads don't address the viewer's health, body or finances. The real product photo anchors every ad, and static images and presenter shots are checked against it by a vision model before they ship.

Languages

Ads are written in English unless you pass language. When you do, the on-screen text, scripts, lyrics and primaryText are all written in that language, the way a native speaker would say them. Voice-overs use a native speaker of that language wherever the voice library has one; for a few languages, such as Albanian, a multilingual voice reads it instead. If the store's page is in a different language from the ads, its facts and reviews are translated, while brand names, product names, prices and discount codes stay exactly as the store writes them.

Pricing

Credits
Reading the page1
static-ad (2 variants)6
ugc-ad25
greenscreen-ad25
animated-ad37
music-ad50
render: true+1

A store's default pack is 44 credits (45 rendered). Credits are reserved when the job starts and refunded automatically if it fails.

Using Claude, ChatGPT or another AI assistant? Connect the VidGuy MCP server and ask it to "make ads for this store". The generate_ads_from_url tool takes the same options at the same prices.