ugc-ads

# /pika:ugc-ads ## Parameters | Param | Default | Notes | |---|---|---| | `url` | required | product URL — drives category detection and beat substitution | | `avatar_url` | built-in fallback | persona portrait URL; fed as `@Image1` reference. When omitted, the skill uses a pre-generated Pixar-style female creator portrait | | `provider` | `seedance` | seedance: strong at UGC selfie / talking-head POV with native lip-sync, multi-segment in single prompt, supports 3:4. kling: explicit `shots[]`, 9:16/16:9 only | | `aspect_ratio` | `9:16` | `3:4` is seedance-only (kling rejects 3:4) | | `variants` | unset | Optional comma list for shared-generation exports. Supported: `9:16`, `16:9`, `1:1`. Keeps the expensive UGC render shared, then reframes the final stage. | | `category` | auto | `HAUL` / `APP` / `FOOD` / `BEAUTY` / `FITNESS` / `TECH`; auto-picked from URL | | `captions` | `true` | TikTok-style word-chunked captions burned on top of the final video | ## Cost transparency gate Before any paid MCP call, call `identity_balance({verbose: true})` once. Surface the current balance, recent burn rate, and remaining runway, then gate the run with this exact message: > Estimated cost: about 4,000 credits (~$40) for a typical Seedance UGC ad with fallback/retry budget. This exceeds $5, so Reply `proceed` to continue or `cancel` to stop. Do not call any paid MCP tool until the user replies `proceed`. If the user replies `cancel`, stop without generating. The gate runs after the product URL is known and before avatar analysis, screenshot capture, video generation, captions, or paid retries. ## Runtime expectations Typical end-to-end run: **6–12 minutes**. Breakdown: - Step 1 (WebFetch) + Step 3 (capture_website screenshot): ~10–30s - Step 7 (`generate_reference_video`): ~3–5 min for seedance, ~5–7 min for kling - Step 7b/c (cartoonize + retry): adds ~1–2 min if seedance moderation rejects the avatar - Step 8 (deterministic brand/spec overlays): 1-2 `edit_text_overlay` calls, ~30s–5 min total - Step 9 (captions): single `add_captions` call, ~30s–5 min (transcribe + burn in one shot) If the run exceeds 15 min without progress, something is wrong — inspect the tool-reported generation status and error message. ## Pre-generation wall-clock guard Start a timer at skill start once the product URL is available and the cost gate has passed. Time spent waiting for the user's `proceed` reply is not prep time and must not trigger this guard. The first paid generation call is `generate_reference_video`, the long-pole paid stage, and it must be invoked within 5 minutes of skill start. If you have not invoked `generate_reference_video` within 5 minutes of skill start, stop before any paid generation call and report `failed_pre_generation_timeout` with what you have so far: fetched product facts, chosen category, avatar source, screenshot status, draft dialogue, and the exact blocker. Do not keep refining script wording, prompt grounding, or shot order. Print a single-line progress checkpoint after each prep stage and right before the paid generation call: - `Stage 1/3 done — product fetched and categorized.` - `Stage 2/3 done — avatar and screenshot ready, composing dialogue.` - `Stage 3/3 done — prompt locked, calling Seedance now.` Script and prompt iteration is maximum 2 passes. After the max 2 passes, ship what you have to `generate_reference_video`; do not continue polishing the hook, punchline, or screen-close-up wording. ## Long-running task_status polling When any long-running generation or edit call returns a `task_id` with or without an initial status, including `{task_id}`, `{task_id, status: "queued"}`, or an initial `queued`, `running`, or `processing` status, record the task id and start time immediately. - Call `task_status({task_id})` in a tight loop until terminal (`completed | failed | cancelled`). No manual sleep and no Bash polling; the worker holds each status call open. - Emit ONE visible progress line every 60s while status is `queued`, `running`, or `processing`: `Seedance i2v queued for {N}m {S}s... still processing`. Replace the provider/stage label when polling Kling, GPT-image-2, caption, or edit tasks. - On `completed`, unwrap the returned result URL and continue. - On `failed` or `cancelled`, surface failure to the user with `task_id`, status, and the last status message. - After 15 min total from the original submit, call `task_cancel({task_id})` if the task is still non-terminal, then surface failure to the user. If cancel reports the task is already terminal, call status once more and report that terminal result. - Do not submit a duplicate request while the original task is still `queued`, `running`, or `processing`. - Async polling budget: one active task with one 15 min polling window. After the polling cap is exhausted, cancel the task and surface failure instead of submitting another paid render unless a later step explicitly allows a separate capped retry after the original task is terminal. ## Engine choice: Seedance default, Kling fallback Default to Seedance for UGC selfie/talking-head ads because it handles native lip-sync, single-prompt multi-beat pacing, and optional 3:4 output well. Use Kling when the caller explicitly passes `provider=kling`, or after Seedance exhausts the capped cartoonized retry only if the user chooses Kling from the stop message. Kling's tradeoff is stricter aspect-ratio support but a separate moderation path and explicit shot segmentation. ## Steps ### 0. Resolve input (empty-args menu) Strip flags and `key=value` parameters from `$ARGUMENTS`. If no product URL remains and there is no usable product URL in prior context, print this menu and stop: > **Which product should the UGC ad promote?** Required: > > - **Product URL** — page to fetch for product name, category, visual references, and language > > Optional: `avatar_url=`, `provider=seedance|kling`, `aspect_ratio=9:16|3:4`, `variants=9:16,16:9,1:1`, `category=auto|HAUL|APP|FOOD|BEAUTY|FITNESS|TECH`, `captions=true|false`. If the product URL is present, skip this step silently. ### 1. Fetch + categorize `WebFetch` the URL: pull `product_name`, `brand_name`, value prop, brand color, product form, packaging, hero copy, target user, category, **and the primary language of the page**. Use `category=` if passed; else trust the WebFetch signal; fall back to HAUL for physical, APP for digital. Build two grounded fact lists from the fetched page: ```json { "grounded_specs": [ { "claim_text": "250W total output", "value": "250", "unit": "W", "source_quote": "visible source-page text containing the exact value", "source_url": "<product URL>" } ], "claims_allowlist": ["250W total output"] } ``` Every numeric spec claim (`W`, `mAh`, `%`, minutes, ports, price, dimensions, counts, charging speeds, battery size, rankings) must come from visible source-page text and include a `source_quote`. If the source page does not visibly support a number, leave it out of `grounded_specs` and `claims_allowlist`. Do not infer specs from product category, model name, common knowledge, or competitor pages. ### 2. Resolve the avatar (fallback to built-in if missing) - If `avatar_url` was passed → use it as-is. - If NOT passed → use this built-in fallback: ``` https://cdn.pika.art/v2/files/agent/17d62bf9-0edb-49e4-9ba9-2c5419fa518f/seedream-1777624057811.jpeg ``` Pre-generated 3D animated Pixar-style portrait of a young female creator — pre-cartoonized so seedance moderation accepts it directly, neutral enough to fit any category. Note in the final summary that the fallback was used so the caller knows to supply their own portrait for persona consistency next time. ### 2.5 Avatar-type probe for creator portraits Run this probe before Step 7 and before any paid `generate_reference_video` call. It applies to caller-supplied `avatar_url`, the built-in fallback, or any creator portrait chosen as `@Image1`. The built-in fallback is already a non-IP stylized creator, but still document its source in the final summary. Call `analyze_media` once: ``` query: "Classify this image for paid video generation. Is it a photograph of a real human face, an AI-generated realistic portrait, a stylized / illustrated character, or a recognizable trademarked / copyrighted character such as Batman, Pikachu, or Mickey Mouse? Return strict JSON only: { \"avatar_type\": \"real_human\" | \"ai_realistic\" | \"stylized_illustrated\" | \"recognized_ip\", \"recognized_character\": string | null, \"moderation_risk\": \"low\" | \"medium\" | \"high\", \"recommendation\": \"proceed\" | \"warn\" | \"reject\" }. Use null for `recognized_character` when no specific character is recognized; never write \"none\", \"unknown\", or explanatory prose in that field." ``` Route from the result: - **recognized IP / copyright risk** -> **STOP only when** `avatar_type` is `"recognized_ip"`, or `recognized_character` names a specific character (for example `"Batman"`), or when both `moderation_risk` is `"high"` and `recommendation` is `"reject"`. Treat `recognized_character: null`, empty string, `"none"`, `"unknown"`, `"n/a"`, and low/medium `moderation_risk` as not enough to stop by themselves. Run this check before the real/stylized routes. A chibi Batman is still Batman even when `avatar_type` is stylized / illustrated. - **real human / AI-generated realistic** -> proceed normally. - **stylized / illustrated** -> proceed with a visible warning that stylized avatars may be accepted by Kling but can be inconsistent under Seedance moderation; continue only if the user supplied or accepted that avatar. - **trademarked / copyrighted** -> **STOP** before generation. Surface this message: `The avatar appears to be a trademarked character ([X]). Most video providers will moderate this and refuse to generate. Pass avatar_url=<real-looking-photo-url> to override.` ### 3. Capture the product screenshot (best-effort) Call `capture_website` with `mode: "screenshot"`. Use `mobile=true` for handheld-product categories (APP / FITNESS / BEAUTY) so the captured page renders as a portrait phone screen; `mobile=false` for desktop-context categories (HAUL / TECH / FOOD). If the call fails (timeout, browser pool down), retry **once**. If still failing, proceed without the screenshot — the skill is degraded but functional. The close-up beat then describes the page from prose only and Beat 2's `reference_images` is just `[avatar_url]`. Capture URL → `screenshot_url` (or null). ### 4. Compose the prompt The full prompt is a single multi-beat string passed to **one** `generate_reference_video` call. Structural prose (not markdown bullets). Every beat has a `Says: "..."` line for lip-sync. Pacing target ~5.5–6 words per second across the whole 15-second ad (≈85–90 words total). `@Image1` is the avatar, `@Image2` is the screenshot when available. **Write all `Says: "..."` lines in the language detected from step 1's WebFetch.** Both seedance and kling lip-sync handle multilingual; if the product page is Chinese / Japanese / Spanish / etc., the dialogue should be in that language. Hook archetypes from step 5 are language-agnostic — adapt the rhetorical move to the language's natural register. **Spec-grounding rule:** forbid inventing numbers. Any spoken or visual number/unit claim must appear verbatim in `claims_allowlist`. If a number is not in `claims_allowlist`, rewrite the line qualitatively ("charges fast", "multiple ports", "big battery") or omit the claim. Do not say "50% in 28 minutes", "3 ports", "140W", prices, counts, or time windows unless that exact claim is source-backed. **Brand/spec text rendering rule:** Do not ask Seedance or the video model to render the brand wordmark, product wordmark, packaging label, or spec text from prose. Video-model text comes out garbled. The prompt may show `@Image2` as a reference, but any new brand name or spec copy that must be readable is added later by the deterministic Step 8 overlay. ``` HOOK (0–3 sec) <visual setting + creator framing + face/body cue>. Says to camera, fast and energetic: "<hook line>". <style anchor — POV handheld, authentic, raw>. JUMP CUT 1 (3–6 sec) <wide POV — creator's body language, product partially in frame edge>. <face cue>, says fast: "<setup line>". JUMP CUT 2 (6–9 sec) <next visual beat — could be the screen close-up showing @Image2 OR another reaction beat, depending on which beat the dialogue arc puts the reveal>. Says (or voice continues over the shot if it's a screen close-up), fast and confident: "<reveal line>". JUMP CUT 3 (9–12 sec) <next visual beat — same logic; one of the JUMP CUTs is the screen close-up, the others are wide-POV reaction shots>. Says, fast: "<insight twist line>". OUTRO (12–15 sec) <selfie POV, mid-chest framing, same setting>. Says to camera, fast: "<punchline line>". avatar is image 1, asset is image 2 ``` **Screen-close-up beat — exactly one across the ad, position is dialogue-driven:** - Place the screen close-up on whichever JUMP CUT (1, 2, or 3) the *reveal* line lands on. Most ads put it on JUMP CUT 2; if the narrative needs it earlier or later, JUMP CUT 1 or JUMP CUT 3 is fine. Pick by content, not by slot number. - The screen close-up beat shows `@Image2` exactly as-is and includes ONE finger-point gesture (a single finger entering from the frame edge, pointing at the hero text or product — no tap, no swipe, no scroll, no hover-on-CTA). The point gesture is the only screen interaction in the entire ad. - The other JUMP CUTs are wide-POV reaction beats: hands stay on knees, on the bed, or at sides. **Trust `@Image2`** — when the product page is shown, reference the image; do NOT describe its UI in prose. Describing UI triggers the model to invent extra panels / dropdowns / sidebars / animations. Reference the image; trust it. ### 5. Category essences Each essence is the brief you read before composing the 5 beats. Pick one from category in step 1 and write the actual `Says: "..."` lines tailored to the real product. **Category numeric guard:** category archetypes are rhetoric/camera guidance, not permission to invent dates, durations, counts, discounts, costs, ratings, charging times, port counts, output figures, or urgency windows. Any numeric phrase must be rewritten unless the exact claim appears in `claims_allowlist`. When `claims_allowlist` lacks a matching number, use non-numeric language such as "after using it", "during the routine", "the source-backed spec", "launch offer", or "available now". #### HAUL_UNBOX - **When to use & why**: fashion, handbags, jewelry, shoes, designer drops, streetwear, luxury cosmetics with packaging story, accessories — anything where brand packaging + texture/material is the value prop. Viewers convert on vicarious-unboxing dopamine + "I just got this" social proof; texture and hardware ARE what the customer pays for, so the close-up lands on materials, not function. Not TECH (→ TECH_UNBOX), not skincare/makeup application (→ BEAUTY_APPLY). - **Sensory anchors**: tissue rustle, fabric slide, hardware clinks (chains / clasps / buckles), leather/fabric grain under fingertips, foil glint. - **Setting**: white unmade bed in natural window light; bathroom mirror in background for the outro held-up reveal; streetwear drops may use desk/floor. - **Close-up beat device**: NOT a screen — product close-up. `@Image2` is a product photo (or brand-site mobile view); the single finger-point lands on a hardware detail (chain, clasp, embossed logo). - **Dialogue character**: hook is **mystery tease** — frame the unboxing as something the viewer doesn't yet know the contents of; do NOT name the product in the hook line. Arc: hook the unboxing mystery → brand name + drop context → reveal the material/silhouette while close-up holds on hardware → tactile/wearability insight (how it feels on the body) → punchline that invites the viewer to imagine themselves with the artifact. #### APP_REVEAL - **When to use & why**: SaaS, AI tools, mobile/web apps, agent-style products, dev tools, productivity tools — anything where the screen IS the product. Viewers convert when they see live UI doing the thing quickly; the close-up beat is the demo, the bookends are the social proof. Not pure hardware (→ TECH_UNBOX). - **Sensory anchors**: micro-thumb gesture, brand-color highlight, UI alive with small motion, ambient room tone. - **Setting**: cozy bedroom or couch POV; jeans/joggers at frame edges; warm window light. - **Close-up beat device**: laptop on bed (desktop screenshot) or phone in hand (mobile screenshot — set `mobile=true` in step 3). - **Dialogue character**: hook is **bewildered curiosity** — the creator can't categorize the thing yet, that's the point. Do NOT use feature lists or marketing language in the hook; lean into "I don't know what to call this" / "this is wild" register that makes the viewer wait for the name. Arc: bewildered hook → name the product + interaction model in human terms ("you just talk to it", "it builds X from Y") → reveal what it produces (concrete comma-separated examples) while close-up shows the page → personal-insight twist (what it replaces / changes in the user's workflow) → punchline + implicit/explicit "go try it" CTA. #### FOOD_ASMR - **When to use & why**: food brands, drinks, kitchen tools, snacks, restaurants with a takeout product — anything where the sensory peak (pour / sizzle / steam / first bite) carries the value prop. Viewers convert on hunger response — show the sensory peak, don't describe it. - **Sensory anchors**: packaging rustle, knife-on-board, sizzle, pour stream, steam rising, satisfied exhale on the first bite. - **Setting**: marble counter or warm wood kitchen, top-down framing. - **Close-up beat device**: a product/dish close-up rather than a screen; phone in hand on the counter only if the brand has a delivery/recipe app. - **Dialogue character**: hook is **show-don't-tell** — frame as a demonstration the viewer is watching unfold, not a description. The hook line lands while a hand or first ingredient is already in motion; the visual carries the curiosity. Arc: demonstration hook → name the product + first impression → narrate the sensory peak as it happens (pour / sizzle / steam) → satisfaction insight ("this is the new default") → punchline that hands off the recipe or shop link. #### BEAUTY_APPLY - **When to use & why**: skincare, makeup, cosmetics, fragrance, hair products, body care — anything where before/after + application ritual is the value prop. Viewers convert on visual transformation under matched lighting; symmetry between hook and outro is what sells the result as real. Not packaging-heavy luxury (→ HAUL_UNBOX). - **Sensory anchors**: pump press, squeeze, glide on skin, glow lift, droplet beading, brush sweep. - **Setting**: bathroom mirror, natural daylight or vanity lighting; same angle for the hook and the outro. - **Close-up beat device**: a product close-up (bottle / tube / compact held in hand), not a screen. - **Dialogue character**: hook is **routine social proof** — signal real use through a specific moment in the routine, not an invented duration. The hook plants the symmetry payoff that arrives in the after-shot. Arc: routine-use hook → name + source-backed key ingredient or claim → narrate the application as it happens (close-up of fingers/brush on skin) → after-shot reveal (same angle as hook) → punchline that signals exclusivity or repurchase intent. #### FITNESS_TRANSFORM