// Playbook for orchestrating an end-to-end UGC video on the agent-media vNext runtime. Read this before deciding whether to call the one-shot make_ugc_video skill or to chain the four primitives (make_portrait → make_character_sheet → make_simple_selfie → make_subtitles) manually.
Generate a 5/10/15s vertical UGC video where your character holds, wears, and shows a product. Provide a character_sheet_url (R2-hosted) and the product image (product_image_url — any https URL — OR product_image_base64; re-hosted to R2 automatically). Two modes: script for a lip-synced talking-head product review (2-4 words/sec), OR scene_action for a silent demo / b-roll. Set subject (e.g. "a young woman") to lock the person's gender/appearance so a gendered product can't drift it. framing: "close_up" (chest-up, default) or "full_body" (head-to-toe, for turn-arounds / showing the whole outfit). Both the person and the exact product are locked from the reference images.
Publish a generated agent-media video to the user's connected TikTok, Instagram, or X. Connect channels (OAuth) and post or schedule via the REST API. Use after producing a video with make_ugc_video / make_simple_selfie.
Generate a 5/10/15-second vertical UGC selfie video from a character sheet. Two modes: provide a script for a lip-synced talking-head (2-4 words/sec), OR provide scene_action for a non-speech clip (dancing, b-roll, vibes) with optional background_music and no dialogue. Subject is framed waist-up, hands free, TikTok aesthetic.
Bring your own audio: lip-sync a face (an R2-hosted image / character sheet, OR an existing clip) to a provided audio track. No text-to-speech or voice cloning — the character speaks your uploaded recording. Output is a 9:16 talking-head video.
End-to-end UGC video in one call. Provide EITHER a text description of the person, OR a portrait URL (R2-hosted), OR an uploaded image. The pipeline auto-generates the missing portrait, builds a character sheet, and produces a 5/10/15s vertical selfie video with native lip-synced audio of your script.
Generate a photographic storyboard / wireframe board from a character sheet (R2-hosted) + script. Multi-panel grid showing the same person performing the action progression, 4 / 6 / 8 / 10 numbered panels.
| name | Agent-Media UGC Playbook |
| description | Playbook for orchestrating an end-to-end UGC video on the agent-media vNext runtime. Read this before deciding whether to call the one-shot make_ugc_video skill or to chain the four primitives (make_portrait → make_character_sheet → make_simple_selfie → make_subtitles) manually. |
| allowed-tools | ["mcp__agent-media__make_portrait","mcp__agent-media__make_character_sheet","mcp__agent-media__make_simple_selfie","mcp__agent-media__make_product_in_hands","mcp__agent-media__make_subtitles","mcp__agent-media__make_wireframe","mcp__agent-media__make_lip_sync","mcp__agent-media__make_ugc_video"] |
| x-skill-slug | agent-media-ugc |
| x-skill-version | 1.1.0 |
You're an agent (Claude, Cursor, custom) that needs to produce a finished UGC video on the agent-media vNext runtime. This playbook gives you the three orchestration patterns and the rules of thumb for picking between them.
| Pattern | When to use | Calls | Total time | Total credits |
|---|---|---|---|---|
| A — One-shot composed skill | The user gave you a person description (or a portrait URL) AND a script. You don't need to show intermediate artifacts. | 1 (make_ugc_video) | ~7 min | ~185–385 |
| B — Step-by-step primitives | The user wants to approve each step (portrait, sheet, selfie) before moving on, OR you want different parameters at each stage. | 4 (make_portrait → make_character_sheet → make_simple_selfie → make_subtitles) | ~7–9 min | ~185–385 |
| C — Image-first | The user supplied a portrait image or R2 URL — skip portrait generation. | 3 (make_character_sheet → make_simple_selfie → make_subtitles) | ~6–8 min | ~150–350 |
make_ugc_video (recommended default)Single composed call. The server runs the whole pipeline inside one Temporal workflow and returns a skill_run_id you poll for per-step status.
POST https://api.agent-media.ai/v1/skills/make_ugc_video/run
Authorization: Bearer $AGENT_MEDIA_API_KEY
{
"description": "a friendly young woman, soft daylight, candid framing",
"character_description": "Maya, 27 years old",
"script": "Okay this is wild, I tried the new flow and it actually works.",
"duration": 5,
"subtitles": true,
"subtitles_style": "hormozi"
}
Poll with GET /v1/skills/runs/<skill_run_id> — the response surfaces per-step artifacts (portrait_url → character_sheet_url → video_url) as each primitive completes. Final video has subtitles burned in.
See skills/make-ugc-video/SKILL.md for the schema.
Once you have a video_url, you can post it straight to the user's TikTok / Instagram / X with the publish-to-social skill — POST /v1/social/publish (CLI agent-media social publish, MCP social_publish). The user connects each network once via OAuth (/v1/social/connect). See skills/publish-to-social/SKILL.md.
Use when the user wants tighter control (e.g. regenerate just the portrait, or pick a different character sheet description after seeing the portrait).
1. POST /v1/skills/make_portrait/run { description, realism_target }
→ wait, get portrait_url
2. POST /v1/skills/make_character_sheet/run { portrait_url, description }
→ wait, get character_sheet_url
3. POST /v1/skills/make_simple_selfie/run { character_sheet_url, script, duration }
→ wait, get video_url
4. POST /v1/skills/make_subtitles/run { video_url, style: "hormozi" }
→ wait, get subtitled video_url
Each step's run_id polls via GET /v1/primitives/runs/<run_id>. Show the user each artifact (portrait, sheet, raw video, subtitled video) and ask for approval before moving to the next step if interactivity matters.
Skip step 1 of pattern B. The user's portrait must already live on R2 — either via the agent-media frontend upload, or via the portrait_image_base64 field on make_character_sheet which the API uploads for you.
portrait_image_base64 on make_character_sheet if you only have raw bytes.INSUFFICIENT_CREDITS — user is out. Surface the agent-media.ai billing page link.REFERENCE_URL_NOT_ALLOWED — you passed a non-R2 URL. Re-upload via portrait_image_base64 on make_character_sheet, or to a user gallery.pose: "".submitted — Temporal worker may be restarting. Wait 30s and re-poll; if still stuck after 5 min, the workflow is hung — contact agent-media support with the workflow_id.