UGC clips

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
Paid with	Appeeky 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

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/<name>.yaml      a video to make
appeeky/ugc/personas/<name>.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) and pull it:

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:

# 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

# 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:

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:

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

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/<brief>.mp4 (gitignored). The brief records status: generated, clipFile, fal’s videoUrl and costUsd. Use the videoUrl in a social draft’s 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

A pull request adds briefs under appeeky/ugc/briefs/, often next to a listing change or a social draft.
The pull request report lists the clips the merge would make, with persona, length and script.
You merge.
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:

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 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 writes it as a brief when a persona is ready. Related: Social posts · Experiments and screenshots · On your own keys

Get started

Your listing

Know your market

Grow

Automate

Reference

Files

Personas

Write a brief

Make clips through Appeeky

Make clips on your own fal key

Asking before paying

Review and send

Measure

​Files

​Personas

​Write a brief

​Make clips through Appeeky

​Make clips on your own fal key

​Asking before paying

​Review and send

​Measure

Files

Personas

Write a brief

Make clips through Appeeky

Make clips on your own fal key

Asking before paying

Review and send

Measure