hiapi-seedance-2-0-ugc-ad-video-skill

HiAPI Seedance 2.0 UGC Ad Video

Create vertical product ads that feel like a creator genuinely demonstrating a product, while keeping every product claim, likeness, and output artifact auditable.

Reuse the installed hiapi-seedance-2-0-video implementation for payload validation, task submission, polling, and download. Do not rewrite the HiAPI transport. This skill adds the UGC research, scripting, reference-asset, campaign-variant, and QC layers.

Hard gates

• Use a real person's image only when the user supplied it or identified an approved asset and confirmed permission to use that likeness. Do not imitate a celebrity, public figure, customer, or creator endorsement.
• Label a generated actor as synthetic in the brief. Do not present a synthetic performance as an unscripted customer testimonial.
• Ground benefits, specifications, prices, discounts, comparisons, and results in the user's materials or current primary sources. Do not invent reviews, usage history, before/after results, scarcity, or personal experience.
• Treat health, medical, supplement, weight-loss, finance, alcohol, gambling, and other regulated categories as review-required. Check current official platform and jurisdiction rules before producing final ad copy.
• Do not place unverified text, labels, prices, or badges inside the generated video. Add captions and offer text in post only after verifying the spoken audio.
• Do not publish, schedule, or upload publicly unless the user explicitly asks for that separate action.
• Do not generate at 4k or use paid persistent storage without explicit cost confirmation.

Defaults

Use these when the request does not specify them:

• Platforms: TikTok and Instagram Reels
• Aspect ratio: 9:16
• Duration: 10 seconds
• Resolution: 720p for a draft; use 1080p when the user requests delivery quality
• Audio: Seedance native dialogue enabled
• Structure: one continuous handheld shot with four micro-beats
• Language: match the user or the target market they name
• Storage: temporary output, downloaded locally
• Batch: three independent creative variants rather than one overloaded multi-cut generation

Keep each Seedance task between 4 and 15 seconds. For a 20–30 second ad, plan two or three independently valid clips and assemble them only after every clip passes QC.

Workflow

1. Build a grounded product brief

Collect or infer only safe creative choices:

• product name, category, URL, and clear product images
• target buyer, problem, differentiator, offer, and CTA
• source-backed claim ledger and forbidden claims
• platform, target market, language, duration, and batch size
• format: unboxing-reveal, first-use-demo, direct-to-camera-demo, problem-solution, try-on, or creator-comparison
• talent source: user-provided, hired-creator, or synthetic-generic
• approved actor image, product image, first-frame plate, or reference media

Research a supplied product URL when the visible page does not contain enough information. Prefer the official product page, product manual, verified merchant listing, and current official policies. Separate sourced facts from creative staging.

Copy assets/ugc-brief.example.json into the task workspace and replace the demo values. Keep the exact spoken line in both creative.script and creative.seedance_prompt.

Run:

node scripts/validate-ugc-brief.mjs /absolute/path/to/ugc-brief.json

Fix every error before generation. Treat warnings as explicit review items.

2. Choose one creative angle

Read references/ugc-playbook.md when selecting formats, beat timing, authenticity signals, batch variants, or platform adaptations.

Choose one promise per ad. Prefer a visible product action over adjectives:

• unbox one package
• apply or use the product once
• show one control or feature
• compare one before/after state only when real evidence exists
• name one benefit and one CTA

Use a spoken hook, not generated overlay text. Save the optional short hook overlay and captions for post-production.

For a campaign batch, vary one dimension at a time:

• Hook A: pain recognition
• Hook B: unexpected discovery
• Hook C: product-first visual reveal

Keep the product facts, offer, talent rights, and CTA source consistent across the batch.

3. Write for natural speech

Write contractions, pauses, self-corrections, and simple words that fit the target market. Avoid polished brand-copy cadence.

Use these speaking budgets:

• English: aim for about 2.0–2.8 words per second
• Chinese: aim for about 3.5–5.0 spoken characters per second

Build a 10-second ad with this default beat map:

1. 0.0–1.5s — spoken or visual hook; product already visible
2. 1.5–4.0s — unbox, apply, wear, or bring the product closer
3. 4.0–8.0s — demonstrate one sourced feature or visible result
4. 8.0–10.0s — natural reaction and one CTA

Do not claim “I have used this for weeks,” “this cured,” “everyone loves,” or equivalent experience/result language unless the claim ledger supports it and the talent is authorized to say it.

4. Choose the Seedance media mode

Use exactly one mode:

1. First-frame plate — best control. Use a verified 9:16 image already showing the approved talent with the exact product. Pass it as production.first_frame_url or production.first_frame_path.
2. Multimodal references — use separate approved actor and product images. Put them in production.reference_image_urls or production.reference_image_paths.
3. Text only — use only for generic concept drafts. Warn that product, packaging, and talent fidelity will be lower.

Do not mix first/last-frame inputs with multimodal references. Keep actor identity, product geometry, packaging colors, cap orientation, label placement, and approved wardrobe stable.

If a hero plate must be created first, use an available image editing skill with the actor and product references, then visually inspect the native-resolution image before calling Seedance. Do not accept a plate with mutated packaging, fabricated text, extra fingers, or an altered face.

5. Direct the performance

Make the Seedance prompt include:

• exact duration, 9:16, and one-shot or clip topology
• exact approved dialogue in quotation marks
• product starting position and one dominant physical action per beat
• relaxed eye line, small hand gestures, natural blinks, breath, and micro-pauses
• handheld phone feel, slight autofocus/exposure breathing, realistic skin texture, ordinary room light, and modest background detail
• useful native sound: dialogue, room tone, package tear/click, or product-use sound
• negative constraints: no cuts unless planned, no beauty filter, no actor drift, no product mutation, no duplicate product, no invented label text, no extra fingers, no unrelated logo, no subtitles, no watermark

Avoid “cinematic commercial,” perfect symmetry, luxury studio lighting, aggressive dolly shots, or model-like posing unless the brief explicitly calls for a polished hybrid ad.

6. Dry-run the real payload

Locate the installed adjacent skill in this order:

• ~/.codex/skills/hiapi-seedance-2-0-video-skill
• ~/.codex/skills/hiapi-seedance-2-0-video
• HIAPI_SEEDANCE_SKILL_DIR when explicitly configured

Run the wrapper from this skill directory:

node scripts/run-ugc-seedance.mjs /absolute/path/to/ugc-brief.json --dry-run

The wrapper imports the adjacent skill's tested payload builder. It converts local media paths to data URIs inside Node, so large references are not passed through shell arguments. Review the redacted payload and confirm:

• model is seedance-2.0
• duration is 4–15
• ratio is 9:16
• resolution is intended
• generate_audio matches the brief
• exactly one media mode is present
• only approved references are present

7. Generate only when requested

For an actual video request, require HIAPI_API_KEY in the environment, then run:

node scripts/run-ugc-seedance.mjs /absolute/path/to/ugc-brief.json

If the user only asks for concepts, scripts, prompts, or a production plan, stop before this command and return the complete brief.

For a batch, use one brief per variant and preserve a stable campaign ID plus variant label. Change the intended angle; do not silently change product claims. The current HiAPI Seedance 2.0 task schema does not accept a client-supplied seed.

The runner prints the HiAPI task ID immediately after task creation. If polling or download is interrupted by a transient network error, resume that exact task instead of creating and billing a duplicate:

node scripts/run-ugc-seedance.mjs /absolute/path/to/ugc-brief.json \
  --resume-task-id "tk-hiapi-..."

8. Verify the artifact

Never infer success from an accepted request or task ID.

After download:

1. Probe the MP4 with ffprobe; record duration, dimensions, frame rate, codecs, and audio presence.
2. Extract the opening, demonstration, and final frames.
3. Inspect face identity, hands, mouth, product geometry, packaging, label, product count, and background continuity.
4. Listen to the complete audio or transcribe it. Verify exact language, intelligibility, lip sync, product sounds, and the complete CTA.
5. Reject outputs with fabricated text, clipped speech, face drift, deformed hands, product mutation, disclosure conflicts, or a missing visible demonstration.
6. Add platform captions, safe-zone text, music, or CTA overlays only after the raw generation passes.

If any core product or likeness failure appears, regenerate from a cleaner reference plate or simplify the action. Do not hide a material failure with cropping.

Output contract

Return these sections in the user's language:

1. Assumptions
2. Product Sources and Claim Ledger
3. Chosen UGC Format and Audience Angle
4. Hook Variants
5. Final Script with Time Beats
6. Reference Asset Plan
7. Copy-Ready Seedance Prompt
8. Validated Payload or Exact Run Command
9. Compliance and Disclosure Notes
10. QC Results
11. Artifact Paths — only after real files exist

For a generated result, distinguish created, still processing, failed, and downloaded. Never say “finished” without a real local file or verified remote result URL.

Resources

• Read references/ugc-playbook.md for format selection, timing, prompt patterns, batch design, and QC.
• Read references/github-foundations.md when auditing or updating the skill's open-source basis.
• Copy assets/ugc-brief.example.json as the machine-checkable brief.
• Run scripts/validate-ugc-brief.mjs before every paid generation.
• Run scripts/run-ugc-seedance.mjs for payload dry-runs and real HiAPI execution.