---
slug: "agent-media-skill"
source_type: "skill_md"
source_url: "https://cdn.jsdelivr.net/gh/yuvalsuede/agent-media-skill@main/SKILL.md"
repo: "https://github.com/yuvalsuede/agent-media-skill"
source_file: "SKILL.md"
branch: "main"
---
---
name: agent-media
description: AI UGC video production from the terminal using the `agent-media` CLI.
homepage: https://github.com/gitroomhq/agent-media
metadata: {"clawdbot":{"emoji":"🌎","requires":{"bins":[],"env":[]}}}
---

npm release: https://www.npmjs.com/package/agent-media-cli
agent-media cli github: https://github.com/gitroomhq/agent-media
official website: https://agent-media.ai

# agent-media — AI UGC Video Production & Media Generation

Produce complete UGC videos, Product Acting UGC, and SaaS review videos from the terminal using the `agent-media` CLI.

---

## MANDATORY RULES — READ BEFORE EVERY COMMAND

**You MUST follow ALL of these rules. Violating any rule produces a broken, unwatchable video.**

### Rule 1: ALWAYS use `--actor` — PICK A RANDOM ONE
Every UGC video MUST include `--actor <slug>`. Without an actor, there is no talking head and no lip sync — the video will just be a static image with voiceover.

**If the user hasn't specified an actor:**
1. Run `agent-media actor list` to get the full list of available actors
2. Pick a **random** actor from the list — do NOT always use the same one (e.g., don't always default to `sofia` or `naomi`)
3. Tell the user which actor you picked and suggest they can browse with `agent-media actor list` or pick a specific one with `--actor <slug>`

**NEVER hardcode a default actor.** Every video should feel different — variety in actors is key to quality UGC content.

### Rule 2: ALWAYS count words — 2.5 words per second
Natural speech is 2.5 words/second. Scripts MUST match the target duration **exactly** — too many words sounds robotic, too few words creates awkward pauses and silence:
- **5s video** → 10–12 words (not fewer!)
- **10s video** → 22–25 words (not fewer!)
- **15s video** → 33–37 words (not fewer!)

**CRITICAL**: Count the words before submitting. If the script is too short, ADD more content. If too long, CUT words. A 15-word script on a 10s video = 5 seconds of dead silence. A 50-word script on a 10s video = rushed robotic speech. Both are broken.

### Rule 3: SaaS reviews MUST have screenshots
For any SaaS/product review video, you MUST provide 1-3 product screenshots via `--broll --broll-images`. Without screenshots, the video has no product context — viewers see only a talking head with no evidence of the product.

`--broll-images` accepts both **HTTP/HTTPS URLs** and **local file paths** (local files are auto-uploaded). Images are **semantically matched** to the most relevant broll scene based on filename — so use descriptive filenames! Examples:
- `--broll-images ./dashboard.png,./calendar-view.png` (local files — descriptive names!)
- `--broll-images https://example.com/pricing-page.png,https://example.com/editor.png` (URLs)
- Mix of both works too

If the user provides a product URL but no screenshots, visit the site yourself and extract image URLs from the page.

### Rule 4: SaaS reviews MUST have the product name
Ask the user: "What SaaS product should I review?" Do NOT proceed without it. The product name must appear in the script so it shows up in subtitles.

### Rule 5: Always use `--sync`
Always append `--sync` to wait for the result and get the output URL.

### Rule 6: Name screenshot files descriptively
Broll images are **semantically matched** to scenes by filename. Use descriptive names so the AI assigns the right image to the right scene:
- **GOOD**: `dashboard.png`, `calendar-view.png`, `post-editor.png`
- **BAD**: `screenshot1.png`, `IMG_0042.png`, `image.png`

When saving screenshots for `--broll-images`, rename them to describe what they show.

---

## Prerequisites

The `agent-media` CLI must be installed and authenticated:

```bash
npm install -g agent-media-cli
agent-media login
```

Verify with `agent-media whoami`. If not logged in, run `agent-media login` and follow the OTP flow.

## UGC Pipeline (Flagship Feature)

The UGC pipeline turns a script into a complete video with AI talking heads, B-roll, voiceover, and animated subtitles — one command.

### Flow

Script → Scene splitting → TTS voiceover → AI talking heads + B-roll → Crossfade assembly → Animated subtitles → Background music → End screen CTA

### Basic UGC

```bash
# ALWAYS include --actor for talking heads + lip sync
agent-media ugc "Ever wonder why some videos go viral? Here's the secret..." --actor sofia --sync

# From file
agent-media ugc ./script.txt --actor naomi --sync

# AI-generated script from a product description
agent-media ugc -g "A fitness tracker that monitors sleep quality" --actor marcus --sync
```

### UGC with B-roll

```bash
# With B-roll cutaway scenes mixed in
agent-media ugc "Your script here..." --actor marcus --broll --sync

# With product screenshots as B-roll (REQUIRED for SaaS reviews)
agent-media ugc "Your script here..." --actor sofia --broll --broll-images https://example.com/screenshot1.png,https://example.com/screenshot2.png --sync
```

### UGC Flags

| Flag | Description | Example |
|------|-------------|---------|
| `--actor <slug>` | Library actor for talking heads | `--actor sofia` |
| `--persona <slug>` | Custom persona (cloned voice + face) | `--persona brand-voice` |
| `--face-url <url>` | Direct face photo URL or local file | `--face-url ./photo.png` |
| `--voice <name>` | TTS voice | `--voice nova` |
| `--tone <name>` | Voice tone: energetic, calm, confident, dramatic | `--tone energetic` |
| `--style <name>` | Subtitle style (17 options — pick random!) | `--style tiktok` |
| `-d, --duration <s>` | Target duration: 5, 10, or 15 seconds | `--duration 10` |
| `--aspect <ratio>` | Aspect ratio: 9:16, 16:9, 1:1 | `--aspect 16:9` |
| `--music <genre>` | Background music: chill, energetic, corporate, dramatic, upbeat | `--music chill` |
| `--cta <text>` | End screen call-to-action text | `--cta "Follow for more"` |
| `--broll` | Enable B-roll cutaway scenes | `--broll` |
| `--broll-images <urls>` | Comma-separated screenshot/image URLs for B-roll | `--broll-images url1,url2` |
| `--template <slug>` | Script template (see below) | `--template saas-review` |
| `-g, --generate-script <prompt>` | AI-generate script from description | `-g "yoga mat product"` |
| `--product-url <url>` | Product URL for script generation context | `--product-url https://...` |
| `-s, --sync` | Wait for completion and print output URL | `--sync` |

### PIP Mode (Picture-in-Picture)

PIP mode creates a full-frame talking head with rotating B-roll image overlays in the lower portion. The actor speaks to camera while relevant visuals slide in and out below. Subtitles appear just above the overlay.

```bash
# Basic PIP video — actor speaks to camera with auto-generated B-roll overlays
agent-media ugc "Stop scrolling. If you struggle to grow on social media, consistency beats perfection every time." \
  --actor adaeze --pip --duration 15 --style hormozi --sync

# PIP with specific style
agent-media ugc "Three things I wish I knew before starting my business..." \
  --actor sofia --pip --duration 10 --style tiktok --sync
```

**PIP Options:**

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--pip-position <pos>` | `bottom-center`, `bottom-left`, `bottom-right` | `bottom-center` | B-roll overlay position |
| `--pip-size <size>` | `small`, `medium`, `large` | `medium` | B-roll overlay size (40%, 55%, 70% of width) |
| `--pip-animation <anim>` | `slide-up`, `slide-left`, `slide-right`, `fade`, `scale` | `slide-up` | Overlay entrance/exit animation |
| `--pip-style <style>` | `none`, `rounded`, `shadow` | `none` | Overlay frame style |

```bash
# PIP with bottom-right overlay, large size, slide-left animation
agent-media ugc "Your script here..." \
  --actor adaeze --pip --pip-position bottom-right --pip-size large --pip-animation slide-left --sync

# PIP with rounded overlay and scale animation
agent-media ugc "Your script here..." \
  --actor sofia --pip --pip-style rounded --pip-animation scale --duration 10 --sync
```

**PIP Rules:**
- `--actor` is **required** (PIP needs a talking head)
- Max duration is **15 seconds** (longer videos are split into ≤10s clips with seamless continuity)
- B-roll overlays are **auto-generated** from the script — no `--broll-images` needed
- Script word count rules apply: 2.5 words/sec (15s = ~37 words max)
- Do NOT combine `--pip` with `--broll` — they are separate modes

### Script Templates

| Template | Structure | Best For |
|----------|-----------|----------|
| `monologue` | Hook → Body → CTA | Direct-to-camera talking |
| `testimonial` | Problem → Solution → Result → CTA | Customer stories |
| `product-review` | Intro → Experience → Verdict → CTA | Product reviews |
| `problem-solution` | Hook → Pain → Solution → CTA | Before/after pain points |
| `saas-review` | Hook → Walkthrough → Opinion → CTA | SaaS/app reviews |
| `before-after` | Hook → Before → After → CTA | Transformations |
| `listicle` | Hook → Tip 1 → Tip 2 → Tip 3 + CTA | Tips and lists |
| `product-demo` | Intro → Demo → Recap → CTA | Product walkthroughs |

### Rule 7: ALWAYS use `--style` — PICK A RANDOM ONE
Every UGC video MUST include `--style <name>`. Without a style, you get the same hormozi subtitle every time — boring and repetitive.

**If the user hasn't specified a style:**
1. Pick a **random** style from the list below — do NOT always default to `hormozi`
2. Tell the user which style you picked

**NEVER hardcode a default style.** Variety in styles makes each video feel unique.

### Subtitle Styles (17 styles)

**Popular**
| Style | Look | Best For |
|-------|------|----------|
| `hormozi` | Bold white, yellow karaoke highlight | Business/marketing content |
| `tiktok` | Bold white, orange-red karaoke | TikTok-style UGC |
| `minimal` | Light, fade in/out | Professional, subtle |
| `clean` | White text on dark box | Clean readability |

**Bold & Energetic**
| Style | Look | Best For |
|-------|------|----------|
| `bold` | Cyan neon outline, karaoke | High energy |
| `impact` | Huge text, 2 words, max punch | Short punchy clips |
| `fire` | Red-orange karaoke, dark red outline | Hype / excitement |
| `pop` | Yellow text, 2 words at a time | Attention-grabbing |
| `spotlight` | Gold highlight, deep shadow | Premium / luxury |

**Aesthetic & Soft**
| Style | Look | Best For |
|-------|------|----------|
| `aesthetic` | Subtle, lowercase, airy | Lifestyle / beauty |
| `pastel` | Soft pink tones | Feminine / soft content |
| `glow` | Purple-pink glow outline | Night / party vibes |

**Colorful**
| Style | Look | Best For |
|-------|------|----------|
| `neon` | Green neon text | Tech / gaming |
| `electric` | Cyan text + magenta highlight | Bold creative |
| `gradient` | Blue-to-coral karaoke | Modern / trendy |
| `karaoke` | Green word-by-word | Karaoke-style |
| `boxed` | White bold on solid black box | Maximum contrast |

## SaaS Review Videos

Generate a complete SaaS review video. **ALL FOUR are required — do NOT skip any:**
1. **Product name** in the script (so it appears in subtitles)
2. **`--actor`** (for talking head + lip sync)
3. **`--broll --broll-images`** with 1-3 product screenshot URLs
4. **Script word count** matching duration (2.5 words/sec)

### Step-by-Step Flow (FOLLOW THIS EXACTLY)

1. **Get product name** — ask user if not provided. STOP if missing.
2. **Get 1-3 screenshot URLs** — ask user, or if they give a URL, visit the site and extract `<img>` URLs showing the product dashboard/UI. STOP if no screenshots.
3. **Pick an actor** — ask user or pick a RANDOM one from `agent-media actor list`. Never always use the same one.
4. **Write the script** — MUST be 22-25 words for 10s or 33-37 words for 15s. Too few words = awkward pauses. Too many = robotic. Mention the product name 2-3 times. Count the words before submitting.
5. **Run the command** with ALL required flags:

```bash
# CORRECT — descriptive filenames so images match the right scenes
agent-media ugc "Postiz is the best social media tool I've used. Postiz schedules across twenty-five platforms with AI. Try Postiz today." \
  --actor naomi --duration 10 --style hormozi --broll \
  --broll-images ./postiz-dashboard.png,./postiz-calendar.png --sync

# CORRECT — URLs with descriptive paths work too
agent-media ugc "Postiz is the best social media tool I've used. Postiz schedules across twenty-five platforms with AI. Try Postiz today." \
  --actor naomi --duration 10 --style hormozi --broll \
  --broll-images "https://postiz.com/dashboard-screenshot.png,https://postiz.com/scheduling-view.png" --sync

# WRONG — no actor, no screenshots, script too long
agent-media ugc "Here's how to schedule a post in Postiz step by step..." --sync
```

### Review Flags

| Flag | Description | Example |
|------|-------------|---------|
| `--actor <slug>` | AI actor (**required**) | `--actor naomi` |
| `--broll` | Enable B-roll scenes (**required** for reviews) | `--broll` |
| `--broll-images <paths>` | Screenshot URLs or local files (**required**, 1-3) | `--broll-images ./img1.png,./img2.png` |
| `--duration <s>` | 5, 10, or 15 seconds | `--duration 10` |
| `--style <name>` | Subtitle style | `--style hormozi` |
| `--cta <text>` | End screen text | `--cta "Try it free"` |
| `-s, --sync` | Wait for result (**always use**) | `--sync` |

## Product Acting UGC

Generate creator-style product-in-hand UGC from a product image, actor, scenario template, and short spoken script. Use this when the user wants an actor to hold, react to, smell, present, or demonstrate a physical product.

**Requirements:**
1. **Product image URL** — must be public HTTPS, or upload a local product image first and use the returned URL.
2. **Actor** — `--actor <slug>` is required. Run `agent-media actor list` if the user has not chosen one.
3. **Script or product context** — provide either `--script` for exact words or `--about` so the API can generate a short script.
4. **Word count** — script is capped at `3 words/second × duration` (≤15 words at 5s, ≤30 at 10s, ≤45 at 15s).

### CLI

```bash
agent-media product-acting \
  --product-image https://cdn.example.com/product.png \
  --actor sofia \
  --about "A premium perfume with a warm vanilla dry-down" \
  --template product-in-hand \
  --acting-style honest-review \
  --duration 5 \
  --sync

agent-media product-acting \
  --product-image https://cdn.example.com/product.png \
  --actor naomi \
  --script "I did not expect this perfume to smell this expensive." \
  --template car-selfie \
  --acting-style shocked \
  --sync
```

### REST API

```bash
curl -X POST https://api-v2-production-2f24.up.railway.app/v1/generate/product_acting_ugc \
  -H "Authorization: Bearer ma_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_image_url": "https://cdn.example.com/perfume.png",
    "actor_slug": "sarah",
    "product_name": "Rose Noir",
    "product_description": "Premium rose perfume with a warm vanilla dry-down.",
    "template": "product-in-hand",
    "acting_style": "honest-review",
    "duration": 5,
    "subtitle_style": "hormozi"
  }'
```

### Flags

| Flag | Values | Default | Description |
|------|--------|---------|-------------|
| `--product-image <url>` | HTTPS URL | - | Product image URL (**required**) |
| `--actor <slug>` | actor slug | - | AI actor (**required**) |
| `--actor-variant-id <id>` | UUID | - | Optional actor look/variant |
| `--name <text>` | text | - | Product name |
| `--about <text>` | text | - | Product description used for generated script |
| `--script <text>` | text | generated | Exact actor line |
| `--template <slug>` | `product-in-hand`, `mirror-selfie`, `bathroom-reaction`, `kitchen-counter`, `car-selfie`, `couch-review`, `expert-interview`, `product-closeup` | `product-in-hand` | Scenario framing |
| `--acting-style <slug>` | `raw-selfie`, `shocked`, `angry`, `excited`, `dramatic`, `weird-hook`, `casual-demo`, `honest-review` | `raw-selfie` | Delivery energy |
| `--visual-style <text>` | text | - | Extra pose, camera, or environment direction |
| `--duration <s>` | `5`, `10`, `15` | `5` | Duration |
| `--subtitles` / `--no-subtitles` | boolean | subtitles on | Burn synced subtitles |
| `--webhook-url <url>` | HTTPS URL | - | Completion callback |
| `-s, --sync` | boolean | off | Wait for completion |

**Credit cost:** `30 × duration + 50` credits, plus `5` credits when the API generates the script. **Runtime:** usually several minutes.

## Show Your App Videos

Generate a video where an AI actor holds a phone that displays **your app screenshot** and reads your script, with Hormozi-style word-by-word subtitles burned in.

**Requirements (enforced server-side):**
1. **Vertical app screenshot** — PNG, JPEG, or WebP, height > width (phone portrait). The API rejects landscape.
2. **Public URL** — screenshot must be reachable. Host on R2, S3, your own CDN, etc. Local files are not accepted by the CLI for this command.
3. **Script word count** — capped at `3 words/second × duration` (≤15 words at 5s, ≤30 at 10s, ≤45 at 15s).

### CLI

```bash
# Random actor (recommended — variety is key)
agent-media show-your-app \
  --app-screenshot https://cdn.example.com/my-app.png \
  --script "You really need to try this app — it generates UGC videos in seconds." \
  --duration 5 --sync

# Specific actor
agent-media show-your-app \
  --app-screenshot https://cdn.example.com/my-app.png \
  --script "Try this app, it changed everything for me." \
  --actor sarah --duration 10 --sync
```

### REST API

```bash
curl -X POST https://api-v2-production-2f24.up.railway.app/v1/generate/show_your_app \
  -H "Authorization: Bearer ma_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_screenshot_url": "https://cdn.example.com/my-app.png",
    "script": "You really need to try this app.",
    "duration": 5
  }'
```

### Flags

| Flag | Description | Default |
|------|-------------|---------|
| `--app-screenshot <url>` | Public URL of vertical app screenshot (**required**) | - |
| `--script <text>` | What the actor reads (**required**, ≤3 words/sec × duration) | - |
| `--actor <slug>` | Specific actor slug | random from pool |
| `--duration <s>` | 5, 10, or 15 seconds | 5 |
| `--subtitle-style <style>` | `hormozi` or `none` | hormozi |
| `--webhook-url <url>` | HTTPS completion callback | - |
| `-s, --sync` | Wait for completion | off |

**Credit cost:** 75 flat. **Runtime:** 4–8 minutes (GPT Image + Seedance 2.0).

## Persona Management

Save voice + face combos for consistent UGC across videos:

```bash
# Create a persona from voice sample + face photo
agent-media persona create --name "brand-voice" --voice ./sample.mp3 --face ./photo.png

# List personas
agent-media persona list

# Use in UGC
agent-media ugc "Your script..." --persona brand-voice --sync

# Delete
agent-media persona delete <persona-id>
```

## Add Subtitles to Any Video

```bash
agent-media subtitle <video-path-or-job-id> --style hormozi --sync
agent-media subtitle ./my-video.mp4 --style bold --sync
```

## Pricing & Credit Deduction

### Plans

| Plan | Price | Monthly Credits | ~10s Videos | ~5s Videos |
|------|-------|-----------------|-------------|------------|
| Creator | $39/mo | 3,900 | ~13 | ~26 |
| Pro | $69/mo | 6,900 | ~23 | ~46 |
| Pro Plus | $129/mo | 12,900 | ~43 | ~86 |

Pay-as-you-go credit pack: 3,900 credits for $39 (one-time purchase, never expires).

### How credits are deducted

**Rate: 30 credits per second of video.** 1 credit = $0.01.

| Duration | Credits deducted | Dollar value |
|----------|-----------------|--------------|
| 5s video | 150 credits | $1.50 |
| 10s video | 300 credits | $3.00 |
| 15s video | 450 credits | $4.50 |
| Product Acting setup frame | +50 credits | +$0.50 |
| AI script generation | +5 credits | +$0.05 |
| Subtitles only | 50 credits | $0.50 |

**Deduction order:** Monthly credits are used first (they expire at period end), then purchased credits (never expire).

**Refunds:** If the video generation fails, credits are automatically refunded. Canceled jobs are also refunded.

Run `agent-media credits` to check balance before generating.

## Job Management

```bash
agent-media status <job-id>     # Check job status
agent-media list                # List recent jobs
agent-media download <job-id>   # Download output media
agent-media cancel <job-id>     # Cancel and refund credits
agent-media retry <job-id>      # Retry a failed job
```

## Account

```bash
agent-media whoami              # Current user info
agent-media credits             # Credit balance
agent-media subscribe           # Manage subscription
agent-media login / logout      # Authentication
```

## REST API (v2)

agent-media also has a REST API for programmatic access. Interactive docs at https://agent-media.ai/docs/api-reference

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | /v1/generate/ugc_video | Generate a UGC video |
| POST | /v1/generate/product_review | Generate a product review video |
| POST | /v1/generate/show_your_app | Actor holds a phone with your app screenshot |
| POST | /v1/generate/product_acting_ugc | Actor presents or reacts to your product image |
| POST | /v1/generate/subtitle | Add subtitles to a video |
| GET | /v1/actors | List available AI actors |
| GET | /v1/videos/{jobId} | Check job status |

### Auth

```
Authorization: Bearer ma_YOUR_API_KEY
```

### SDKs

TypeScript SDK: `npm install @agentmedia/sdk`

Python SDK: `pip install agent-media`

### curl Example

```bash
# Generate a video
curl -X POST https://api-v2-production-2f24.up.railway.app/v1/generate/ugc_video \
  -H "Authorization: Bearer ma_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "Your 50+ character script here...",
    "actor_slug": "sofia",
    "tone": "energetic"
  }'

# Check status
curl https://api-v2-production-2f24.up.railway.app/v1/videos/{job_id} \
  -H "Authorization: Bearer ma_YOUR_KEY"
```

### MCP Server (Claude Code / Cursor) — coming soon

```json
{
  "mcpServers": {
    "agent-media": {
      "command": "npx",
      "args": ["@agentmedia/mcp-server"],
      "env": { "AGENT_MEDIA_API_KEY": "ma_xxx" }
    }
  }
}
```

### OpenAPI Spec

Download at https://agent-media.ai/openapi.json — import into Postman, Insomnia, or any OpenAPI tool.

## Checklist Before Every UGC Command

Before running ANY `agent-media ugc` command, verify:
- [ ] `--actor` is included (no actor = no talking head = broken video). Pick a RANDOM actor if user didn't specify one!
- [ ] `--style` is included. Pick a RANDOM style if user didn't specify one — never always use hormozi!
- [ ] Script word count matches duration EXACTLY (5s=10-12, 10s=22-25, 15s=33-37 words — too few = pauses, too many = robotic)
- [ ] `--sync` is appended
- [ ] For SaaS reviews: `--broll --broll-images` with 1-3 screenshot URLs
- [ ] For SaaS reviews: product name appears 2-3 times in script
- [ ] For PIP mode: `--pip` flag is set, `--actor` is included, duration ≤ 15s
- [ ] For PIP mode: do NOT also pass `--broll` (PIP auto-generates overlays)
- [ ] For Product Acting: `--product-image`, `--actor`, and either `--script` or `--about` are included
- [ ] Credits are sufficient (`agent-media credits`)