> ## Documentation Index > Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt > Use this file to discover all available pages before exploring further. # UGC clips > Write short creator-style videos as briefs, review them in a pull request, make them with a persona through Appeeky or on your own fal key, and measure what they bring. Short videos of a person talking about the app are one of the cheapest ways to test a hook. With Appeeky Spec, each video starts as a brief in the repo: a persona, a script and a scene. It is reviewed in a pull request like a listing change, made after the merge, and measured with a smart link. There are two ways to make the clip: | | Through Appeeky | On your own fal key | | - | - | - | | Command | `ugc generate` | `ugc generate --local` | | Needs | `APPEEKY_API_KEY`, UGC access on your account | `FAL_KEY` from [fal](https://fal.ai) | | Paid with | Appeeky [media credits](https://docs.appeeky.com/docs/ugc-overview.md#media-credits) | Your fal account, in USD | | Personas | Made in Appeeky | Made in Appeeky, or kept in the repo | | The clip | Renders in Appeeky | Saved to `.appeeky/media/` | Both make the clip the same way: a still of the persona in the scene, then a talking video with the script in their voice. ## Files ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} appeeky/ugc/personas.yaml creator personas from Appeeky, and whether each can make clips yet appeeky/ugc/clips.jsonl the clips made with them appeeky/ugc/briefs/.yaml a video to make appeeky/ugc/personas/.yaml optional: a persona kept in the repo, for --local ``` ## Personas A persona is the creator in the video. Make one in Appeeky ([Personas and clips](https://docs.appeeky.com/docs/ugc-personas-and-clips.md)) and pull it: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec ugc pull # Personas Mia, Leo (no look yet) # Clips 7 # Written to appeeky/ugc/: personas.yaml, clips.jsonl. ``` A persona needs a look (reference images) picked in Appeeky before it can make clips. `personas.yaml` says `ready: true` when it can, and `ugc pull` marks the others `(no look yet)`. `clips.jsonl` lists the clips made with each persona: script, caption, status, and the social post when one was made from it. For `--local`, you can instead keep a persona in the repo, with its images next to it: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} # appeeky/ugc/personas/mia.yaml name: Mia appearance: early 20s, dyed pink bob, oversized hoodie personality: playful, talks fast lane: dance trends and sound edits looks: [mia/front.png, mia/side.png] # images next to this file, or URLs ``` `looks` is required. Up to six images are used. Personas in the repo work only with `--local`. ## Write a brief ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} # appeeky/ugc/briefs/2026-11-10-before-after.yaml persona: Mia script: "I used to lie awake for an hour. Now I put on brown noise and I'm out in ten minutes." scene: bedroom at night, phone on the pillow showing the app caption: the only sleep hack that worked for me durationSec: 8 aspectRatio: "9:16" why: "Before/after hooks drove 2x link installs in October." ``` | Field | Required | What it is | | - | - | - | | `persona` | Yes | A persona name or id from `personas.yaml`, or a file name in `appeeky/ugc/personas/` | | `script` | Yes | What the persona says, word for word. About 8 seconds of speech fits one clip | | `scene` | No | Where it is filmed and what is on screen | | `caption`, `title` | No | For the post | | `durationSec` | No | Length in seconds (default 8) | | `aspectRatio` | No | `9:16` (default) or `16:9` | | `why` | No | The hypothesis, for whoever reviews the pull request: which hook, for whom, measured how | Spec adds `status`, the clip id and the cost when the clip is made. Leave them out of a new brief. ## Make clips through Appeeky Always look at the cost first: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec ugc generate --dry-run # appeeky/ugc/briefs/2026-11-10-before-after.yaml Mia · 186 credits # # 186 credits in all. Nothing was made. ``` Then make them: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec ugc generate # appeeky/ugc/briefs/2026-11-10-before-after.yaml Mia · 186 credits # Make 1 clip for 186 credits? [y/N] y # Started 1. They render in Appeeky; `appeeky-spec ugc pull` records them when done. ``` It makes a clip from each brief still marked as a draft and marks the brief `status: generating` with the `clipId` and `credits`. It stops before spending anything when a brief names an unknown persona (run `ugc pull`), when a persona has no look yet, or when there are not enough credits for every brief. ## Make clips on your own fal key ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export FAL_KEY=… # fal.ai → API keys npx @appeeky/spec ugc generate --local --dry-run # appeeky/ugc/briefs/2026-11-10-before-after.yaml Mia · 8s 9:16 · veo-3.1-fast · about $1.24 on fal # # About $1.24 on your fal account in all. Nothing was made. npx @appeeky/spec ugc generate --local # appeeky/ugc/briefs/2026-11-10-before-after.yaml Mia · 8s 9:16 · veo-3.1-fast · about $1.24 on fal # Make 1 clip on fal for about $1.24? [y/N] y # appeeky/ugc/briefs/2026-11-10-before-after.yaml # still: the persona in the scene # video: the persona says the script # ✓ .appeeky/media/2026-11-10-before-after.mp4 ``` The persona comes from `appeeky/ugc/personas/` first, then from Appeeky when `APPEEKY_API_KEY` is set. An Appeeky persona's cover image is its look. fal bills your account directly, and no Appeeky credits are used. The clip is saved to `.appeeky/media/.mp4` (gitignored). The brief records `status: generated`, `clipFile`, fal's `videoUrl` and `costUsd`. Use the `videoUrl` in a [social draft's](https://docs.appeeky.com/docs/spec-social.md) `media:` to post it. ## Asking before paying Both ways quote first and ask before they spend. `--dry-run` only quotes. `--yes` skips the question; without it, a script with no terminal makes nothing. The push workflow passes `--yes` because the merge is the approval. ## Review and send 1. A pull request adds briefs under `appeeky/ugc/briefs/`, often next to a listing change or a social draft. 2. The [pull request report](https://docs.appeeky.com/docs/spec-ci.md#pull-request-report) lists the clips the merge would make, with persona, length and script. 3. You merge. 4. The push workflow from `init --ci` (or the Docker `push` routine) runs `ugc generate --yes`, adding `--local` when `FAL_KEY` is set, and commits the updated briefs. Clips made with `FAL_KEY` are kept with the workflow run. The weekly agent writes briefs and may quote them with `--dry-run`, but is never allowed to make clips. ## Measure Run each video as an experiment with a smart link, so its installs and revenue are counted: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec experiment add --type ugc --persona sleepless-parent --link tiktok \ --hypothesis "Before/after hooks get installs" --metric link_installs --target 50 \ --asset appeeky/ugc/briefs/2026-11-10-before-after.yaml ``` Put the printed link in the post or bio. `verify` fills in the result from the link when it is due, and `--playbook` adds it to `appeeky/playbook.md`, so the next brief starts from what worked. See [Attribution](https://docs.appeeky.com/docs/spec-attribution.md#smart-links) for the iOS caveat. The `appeeky-ugc` specialist reads past UGC experiments, link results, personas and the words users use in reviews, and proposes the next video. The [co-founder review](https://docs.appeeky.com/docs/spec-growth-team.md) writes it as a brief when a persona is ready. Related: [Social posts](https://docs.appeeky.com/docs/spec-social.md) · [Experiments and screenshots](https://docs.appeeky.com/docs/spec-experiments.md) · [On your own keys](https://docs.appeeky.com/docs/spec-own-keys.md#ugc-clips-on-fal) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.