---
name: ppl-studio
description: Make AI UGC marketing content with ppl.studio — creator videos from a product URL, TikTok/Reels ads, testimonial and app-demo videos, lip-sync monologues, animated story ads, product photo packs (Amazon, Shopify), TikTok carousels, UGC photos, ad scripts and hooks — through the ppl.studio MCP tools or its REST API. Use when the user wants UGC, AI creator or influencer-style content, product photos, short-form video ads, hooks or ad scripts, or mentions ppl.studio.
---

# ppl.studio — AI UGC

ppl.studio makes UGC-style marketing content with AI: a recurring AI creator
(a "persona") talks about the user's product on camera, holds it in photos,
or fronts a carousel. Everything runs on ppl.studio's servers, on the user's
account and plan. Video renders on the user's own Google Gemini key.

## 1. Pick the way in

Check, in this order:

1. **ppl.studio MCP tools are available** (tool names like `get_account`,
   `list_presets`, `start_run`). Use them; everything below names them.
   The local server can read files the user names and save results to disk;
   the hosted one (`https://ppl.studio/mcp`) works with URLs only.
2. **A shell and `PPL_API_KEY` are available** (Claude Code, a terminal). Use
   the REST API with curl — recipes in `references/api.md`.
3. **Neither**: tell the user how to connect, then stop:
   - claude.ai / Claude Desktop / ChatGPT: add a custom connector with the URL
     `https://ppl.studio/mcp` and sign in.
   - Claude Code: `claude mcp add --transport http ppl-studio https://ppl.studio/mcp`
     (then `/mcp` to sign in), or the local server that saves files:
     `claude mcp add ppl-studio --env PPL_API_KEY=ppl_live_… -- npx -y https://ppl.studio/downloads/ppl-studio-mcp.tgz`
   - Keys: https://ppl.studio/account/api-keys. Setup for every client:
     https://ppl.studio/features/mcp

## 2. Rules that protect the user's money

- **Video is the expensive step.** Runs stop at a *priced preview* (the
  frames, the line said over each, and `estimate.usd`) before any video is
  made. Show the user the frames, lines and price, and call `approve_run`
  (API: `POST /api/v1/flows/{id}/approve`) **only after they say yes to that
  price**. Never start a run with `straight_through` / `straightThrough` unless
  the user explicitly asked to skip the preview.
- Rough costs, billed by Google to the user's key: a photo ≈ $0.045; Veo Lite
  video ≈ $0.05 per second at 720p (an 8-second clip ≈ $0.40); lip-sync
  ≈ $0.005 per second. Photos and text are cheap — no need to ask for those.
- When anything is refused, or before the first video, call `get_account`
  (API: `GET /api/v1/account`): it says the plan, the image allowance,
  whether a Gemini key is connected, and whether video is allowed and why not.
  Video needs the paid plan **and** the user's own Gemini key connected in
  the app — you can't fix either; send them to https://ppl.studio/account.

## 3. Choose the workflow

`list_presets` (API: `GET /api/v1/presets`) lists all of them with what each
needs, its options and an example start body. The common ones:

| The user wants | Preset | Needs |
|---|---|---|
| A UGC video about a product or topic | `creator-ugc-video` | brief, creator |
| A TikTok/Reels video + post caption | `tiktok-reels-short-form` | brief, creator |
| A testimonial ("AI-generated" badge) | `testimonial-video` | brief, creator |
| An app demo (creator + app screen) | `app-demo-video` | product-only brief, creator, app screenshot |
| A product-only demo (no person) | `product-demo-video` | product-only brief, product |
| A 1–4 minute talking monologue | `lipsync-ugc-video` | brief, creator |
| A cartoon story ad with narration | `animated-story-ad` | brief (product optional) |
| A sung drama ad (song VSL): betrayal, a mentor with the product, vindication | `drama-song-ad` | brief (product optional) |
| A TikTok photo carousel | `viral-tiktok-carousel` | brief |
| A texting-story video (a Messages chat typed out; free to render) | `text-message-video` | brief |
| "[App] real or fake?" from the user's own screen recording (payout proof; free to cut) | `screen-recording-video` | product-only brief, `recording` (+ optional `proof` screenshot) |
| A "what's inside" carousel of a box, kit or set (free) | `whats-inside-carousel` | a product with its contents listed |
| An app carousel: list, review, what's new, how-to (free) | `app-carousel` | apps (App Store links) |
| Product round-ups from a feed or shop (free) | `catalog-carousel` | a catalog (feed, shop or CSV) |
| Product photo sets | `product-ugc-photos`, `amazon-listing-pack`, `shopify-product-pack`, `before-after-photo-pack`, `ecommerce-product-photos` | product-only brief, product, creator |

Details and every option: `references/workflows.md`.

## 4. The run loop

1. **Brief.** Easiest: the product page URL →
   `brief_source: { mode: "url", value: "<url>" }` (API: `briefSource`), and the
   run reads it. Or a description (`mode: "description"`). Or fields: `goal`
   (reach · saves · comments · follows · clicks · sales), `platform` (tiktok ·
   reels · shorts · meta-paid · tiktok-paid), `niche`, `product`, `audience`,
   `language`.
2. **Creator.** `personas` action `list` for theirs; if they have none, `personas`
   action `generate` with a niche and `save: true`. Use its `slug`.
3. **Product** (when the preset needs one): `products` action `create` with a
   name, `category` (`handheld` for things held in hand; `app_screen` for app
   screenshots), a description and photos.
4. **Start**: `start_run` with `preset`, the brief, `creator_slug`, `product_id`,
   and `wait_seconds: 600` to wait for the preview.
5. **Preview**: show the frames (with their lines) and `estimate`. Offer changes
   before paying: `edit_run` action `script` (swap in a runner-up or edit lines),
   action `frame` (replace a frame), or `run_step` with `item` to redo one frame.
6. **Approve** only on a yes, then `wait_for_run` until finished (a clip takes
   ~1 minute on Veo Lite, a lip-sync ~5; call it again when it times out).
7. **Deliver**: local server → `save_run` (writes `final.mp4`, clips, frames,
   `script.txt`); hosted/API → give the user `cut.url` and the frame URLs.
   Post caption: `edit_run` action `caption`.

Runs report `next` — what they wait on and which call moves them on. Follow
it. A failed step says why in its `error`; fix the cause, then `run_step`.

## 5. Other jobs

- **One photo**: `generate_image` (persona + scene in words + product held).
  New angle / next moment: `edit_image`. Several: `bulk_images`.
- **Photo packs outside a run**: `photo_pack` (`plans` first, then `make`).
- **Scripts & hooks**: `write_scripts` (talking-head, 2–6 variants on proven
  structures), `write_ad` (ad hooks by angle, 30/60 s ad script, long-form
  monologue), `script_tools` (critique, revise, rank, platform translate,
  localize, caption, topic ideas). Save the chosen one with `saved_scripts`
  `create`, and `saved_scripts` `send` turns it into a video run.
- **What's trending**: `script_tools` action `trends` (`{ niche, medium }`) —
  TikTok's search lists and rising Google searches, the niche's own first,
  each with why. Start a run on one with `brief: { niche: title,
  nicheOverride: niche }`; a text-message-video schedule takes a new one each
  turn with `setup.topicSource: "trending"`.
- **Animate one photo**: `start_job` brick `animate`, variant `veo`, input
  `{ items: [{ frame: { url }, prompt, seconds: 8, line }] }` — video spend, ask
  first. `list_bricks` shows every engine step with its input schema.
- **A song on its own**: `make_song` — `lyrics` (+ `genre` or `style`,
  `singer`): sung, with each line's timing. Free within a weekly allowance;
  saved to the gallery.
- **Carousels**: the `viral-tiktok-carousel` preset. From what the user sells,
  with nothing generated (free, no preview): `whats-inside-carousel` (a
  product's `contents`), `app-carousel` (the `apps` tool), `catalog-carousel`
  (the `catalogs` tool) — `options.source`, `recipe`, `deckParams`.
- **A chat you already have, as a video**: `start_job` brick `cut`, variant
  `chat`, input `{ thread: { hook, timestamp?, messages: [{ from: "me" | "them",
  text }] }, seconds?, theme?: "dark" | "light", keyboard? }` — no model, no
  cost, about a minute. `write` / `chat` writes a thread from a topic.
- **Formats**: a run left to auto follows a format from the library (the
  best of what's going viral: `format_tools` action `library`) when one fits
  its niche, and ppl.studio's own formats take turns otherwise. Start one on
  purpose with `options.houseFormat` = its key; `options.account` (from
  `posts` `accounts`) keeps the turns per account. To copy a winner the user
  has — a carousel, a talking-head video, a chat, a story, a demo —
  `format_tools` action `clone_format` with its words (`kind`, `text`); it's
  kept in their formats, and a run on `reference.preset` follows it with
  `options.reference` = the format. Post numbers are paused: don't mark posts
  or log numbers.
- **Anything else**: `api_catalog` finds the endpoint, `api_request` calls it.

## 6. Good UGC, briefly

- Lead with the hook: the first line decides the watch. Offer 2–3 hook options
  (`write_ad` hooks or `script_tools` hooks) when the user hasn't written one.
- Match the platform: `tiktok`/`reels`/`shorts` are organic; `meta-paid` and
  `tiktok-paid` write for ads (clear offer, CTA).
- Keep one creator per brand for consistency; their passport photo is the face
  every render matches (`personas` `set_passport`).
- 9:16 with burned-in captions is the default and right for short-form.

## 7. When things fail

| Error | Meaning | Do |
|---|---|---|
| 401 | Missing, revoked or mistyped key / signed out | Reconnect or make a new key |
| 402, or 403 naming the Gemini key | No Gemini key connected | User connects it at ppl.studio/account |
| 403 naming the plan | Needs the paid plan ($1.99/week) | Tell the user; don't retry |
| 429 | Rate limit | Wait for `Retry-After`, then retry once |
| Step `failed` | That step's `error` says why | Fix, then `run_step` it |

Veo renders one clip at a time per user; more wait their turn — that's normal.

## References

- `references/workflows.md` — every preset: what it makes, inputs, options.
- `references/api.md` — the REST API with curl, for when there is no MCP.
- Full API reference: https://ppl.studio/docs/api · OpenAPI: https://ppl.studio/openapi.yaml