name: ai-video-ad-production description: AI e-commerce video ad production line: one-command product ad video pipeline (product lock, multi-engine selection, official-pixel product inserts, auto overlay assembly). category: ecommerce
AI-generated short product videos (live-action story / voice-over)
When to Use
When the user asks for "short video / promotional video / voice-over video / sample standard", or complains that previous results "lack realism, look like image collages". First, make a path decision (see below) — do not treat image stitching as a deliverable.
🚀 How to Run (As of 2026-09-18: One Command to Generate Video)
Main command = scripts/make_ad.py — consolidates the previous 6 manual scripts scattered in /tmp into a single command.
All subsequent component scripts are called by it as needed.
S=~/.hermes/skills/ecommerce/ai-video-ad-production
# ① First, preview the prompt (free, no submission; confirm product lock + storyboard before spending money)
python3 $S/scripts/make_ad.py $S/templates/ad_project.hsq1.json --steps plan
# ② Fully automated one-stop: submit → poll → download → frame extraction verification → assembly 30s/15s → deliver to desktop
python3 $S/scripts/make_ad.py $S/templates/ad_project.hsq1.json --steps all
# ③ Segments already downloaded, only re-run post-production (change subtitles/voiceover/re-cut to 15s — no cost, most common use)
python3 $S/scripts/make_ad.py <project.json> --steps assemble,deliver
# ④ Process only specific segments / temporarily change runid or resolution
python3 $S/scripts/make_ad.py <project.json> --steps fetch,verify --seg 3 --runid v24 --res 720P
Each step checks exit code + file existence/size. If criteria are not met, it reports the FAIL reason directly and lists it — does not silently continue.
Project Configuration (templates/ad_project.hsq1.json is a real, directly runnable example — modify it to create a new video):
| Field | Description |
|---|---|
model | Engine (Use wan3.0-video for product shots; default wan2.7-r2v only suitable for pure character scenes) |
product | Points to a key in product_profiles.json — Shared between image generation and video generation |
refs | Reference image order = Image 1..Image N, must correspond one-to-one with image descriptions in the product lock template; local images are automatically scp'd to a public URL |
segments | Storyboard text for each segment (Only write "what to shoot"; product lock is automatically prepended by make_ad) |
assembly.vo | Voiceover (edge-tts); timeline = subtitle start, naturally aligned |
assembly.subs/chips/spec/compliance | Subtitles / stylized text / parameter bars / AI-generated content marking |
assembly.cut15 | 15s version: which segments to take, where to cut the voiceover, new time window for each overlay on the 15s timeline |
deliver | Delivery directory + filename (default ~/Desktop/电商素材/<product>/视频/) |
Product Lock (shared across all products, do not create new ones): templates/product_lock_head.txt + video_lock field in the product profile.
"Proportion ≤ 1/6 of frame height, measure using head diameter as ruler (1.9x), bottom end is a flat circular surface, line inserted along the axis, never look directly at the lens…"
These hard-learned phrases are all there — Do not repeat in storyboards, and do not hand-write new templates.
Empirical Evidence (2026-09-18): Running ad_project.hsq1.json with --steps assemble,deliver produces final videos whose md5 checksums perfectly match the manual delivery version from the night of 2026-09-17 (30s 86f3da96…, 15s 0b67686b…);
--steps plan,submit,fetch,verify single-segment smoke test successfully completed (submission → polling → download → frame extraction verification).
Component List (scripts/ 26 items, grouped by purpose)
| Step | Script | Purpose |
|---|---|---|
| Main | make_ad.py | One-command video generation (plan / submit / fetch / verify / assemble / deliver) |
| Generation | videoretalk_submit.py / probe_model_availability.py / compare_video_models.py | Lip-sync submission / Model availability probe (successful submission ≠ availability) / Cross-model comparison for same prompt |
| Verification · Product | product_fidelity_zoom.py / scale_consistency_check.py / scale_panel_check.py / measure_product_truth.py / check_reference_image.py / locate_reported_frame.py / audit_shots.py | 2x product zoom / Cross-shot size consistency / Truth + output frame reading panel / Real product aspect ratio ground truth / Reference image health check / User screenshot timestamp lookup / Per-shot audit |
| Verification · Audio | stt_dialogue_check.py / voice_consistency_check.py / voice_timbre_similarity.py / tts_fit.py | Speech-to-text reverse check of lines (subtitle timeline source) / Voice change detection / Voice timbre locking verification / TTS speed adjustment for shot alignment |
| Verification · Visual | verify_motion.py | Motion detection — determines if the final video is a "static image collage" |
| Post-production | assemble_r2v_overlays.py / build_vo30.py / overlay_anim.py / replace_segment_audio.py / gen_ass.py | Assembly (supports vo full voiceover track) / Voiceover track / Stylized text animation / Replace audio within segment / ASS stylized text |
| Zero Distortion Path | build_official_product_insert.py / compose_official_material_ad.py / cutout_product.py / make_comp_cards.py | Official pixel-perfect product insert (top choice for product shots, 0 cost) / Official material dynamic effect video / Official image cutout to transparent PNG / Composite cards |
| Characters | gen_character_candidates.py | Male lead candidate generation (produces 3-4 collages at once for user to choose) |
Path Decision (Most Important · Hard-Earned Lessons; Rewritten 2026-09-19)
| Path | Effect | When to Use |
|---|---|---|
① Product Lock + wan3.0-video ✅ Current Main Path | With same prompt and same 5 reference images, product is correct on first try, no degradation across entire segment; realistic human life scenarios. Reference images = macro mesh shot / front full body / real hand scale / bottom end face / male lead | Most promotional videos (have official product images, require "product looks like real device") |
| ② Official Pixel-Perfect Product Insert (0 API Cost) ✅ Ultimate Product Fidelity Solution | Product 100% equals real device (official pixel-perfect, no AI involved) | When AI consistently fails to draw the product accurately; or when the video needs viewers to instantly recognize the product |
③ Text-to-Video (wan2.6-t2v, lines via input.audio_url) | Real people + scene + Chinese lip-sync, but product changes slightly in each segment | No official materials, or purely character-based story |
| ④ Image Stitching (clipforge / MoneyPrinterTurbo) | ❌ User verdict = "image collage, lacks realism, far from sample quality" | Only for draft placeholders, not acceptable as final delivery |
| ⑤ Digital Human Lip-Sync (wan2.2-s2v / EMO / videoretalk) | Single person voiceover, weak environmental realism | Only need voiceover narration |
Recommended Combination: Character/life scene shots → ①; Product appearance/close-up shots → ②.
Final video structure = "Hook 5s (AI) + Official product insert 3s (pixel-perfect) + Main content 7s (AI)" = 15s;
Script scripts/build_official_product_insert.py (crops official image to create 3s vertical product insert, subtitles/stylized text offset by +3s).
Ironclad Rules:
- ❌
wan2.7-r2vfor product shots is retired (product appears small/blurry/easily washed out to silver-white = root cause of repeated rework); use only for character scenes - Generation is always at 720P (native 1080P generation = re-rolling, not an upgrade; in practice, product deformation/loss of gold/details no sharper) → Final video is upscaled to 1080 during assembly
wan3.0-videotreats reference image 1 as the first frame (control the opening by changing image 1)- If the user's "sample standard" shows a real person dialogue scene, do not assert it "can only be shot live" (user explicitly corrected this: their sample itself was AI-generated)
- Image stitching (④) can never match the realism of ①; do not pass it off as an AI video deliverable; directly use ①/② with the user's own lines and voiceover
Backup Route Recipe: wan2.6-t2v (Real Person Story · Product May Vary)
Complete parameters, JSON, billing, voiceover hosting, and verification commands are in references/scene-drama-and-candid-style.md.
Quick Highlights:
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesismodel=wan2.6-t2v, headerX-DashScope-Async: enableparameters:size:"720*1280"(9:16) or"1080*1920",duration:5|10,shot_type:"multi",prompt_extend:trueinput.audio_url: Pass our own written lines as audio (3~30s mp3/wav public URL) → Model performs lip-sync based on the audio; If not provided, the model auto-generates sound effects and makes up its own lines (uncontrollable, selling points will drift)- Pricing: 720P 0.6 CNY/second, 1080P 1 CNY/second; account has 50 seconds free quota → First 30-second video can be generated at 0 cost using quota
- Voiceover timbre: edge-tts
zh-CN-XiaoyiNeural(young female) /zh-CN-XiaoxiaoNeural(older female) /zh-CN-YunxiNeural(male) - In the prompt, use
1st shot [0-4 seconds]…2nd shot [4-10 seconds]…to describe multiple shots; add "No text, subtitles, or watermarks should appear in the video" at the end
Standard Production Workflow
- Script: 3 segments × 10 seconds (or 6 segments × 5 seconds): Story hook → Product introduction + real selling points → Conclusion + CTA
- Voiceover: Generate mp3 for each segment using edge-tts →
scp yunvela:/tmp/→sudo mvto/opt/yunvela-site/dh/→curl -o /dev/null -w '%{http_code}' https://yunvela.com/dh/segN.mp3must return 200 - Generation: Submit segments one by one (can be parallel), poll
GET /api/v1/tasks/<id>,curl -sL --retry 3 --retry-all-errorsto download - Post-production: Stitch + stylized text (white text with black outline + yellow keyword box) + emoji stickers + BGM → Final 9:16 video
- Verification (cannot be skipped) :
ffprobefor duration/resolution/audio track presence +volumedetectto confirm audio is present + extract frames for visual inspection + STT reverse check of lines (~/.hermes/scripts/voice_stt_local.py) to confirm the spoken words match our script - Delivery: Sending large videos via WeChat gets throttled by iLink →
~/.hermes/scripts/feishu_send_media.py <video> "description"
User Preferences (Confirmed in This Project)
- 🔴 Do not entrust product close-ups to AI — use official product images for dynamic effects (empirical conclusion from 2026-09-15):
In AI-generated character story segments, the product "varies slightly" in each segment (our test: under the same prompt, one segment shows a constant-diameter cylinder, another becomes a tapered rod with a mesh head, and even repeated logos appear).
Correct approach: Hand character scenes to AI, for product close-ups, use official product images with a slow Ken Burns zoom-in
(
scale=1080:-1,pad=1080:1920:(w-h)/2:(w-h)/2:white,zoompan=z='min(zoom+0.0007,1.10)':d=<number of frames>), and attach the original segment's voiceover to the official image dynamic effect (no sentence break). This makes the product 100% consistent with the real device, satisfying the client's requirement that "the product must be realistically integrated." - 🔴 Two reference images must be in the "same orientation and form": Both product reference images for r2v must be taken from a vertical perspective (our test: using a "bottom end cross-section view" as the second reference caused the model to average between slender and fat, producing a squat cup-shaped product). Do not mix top-down/upward/cross-section images as references. Reference image process: Crop to object bounding box → Paste onto a white square canvas, with the object occupying about 60% of the canvas height.
- ⚠️ AI may burn in its own subtitles: Even with prompt saying "no text", wan2.6-r2v-flash often adds built-in bottom subtitles. Therefore, place our stylized text at the top (Alignment=8 + large MarginV), and do not overlay another layer at the bottom → otherwise double subtitles will overlap.
- Determine dimensions based on actual measurements, not visual estimation (lesson from 2026-09-15): The prompt's "height:diameter" must be calculated from official dimensions
(HSQ1 = 74×39mm → height:width 1.93:1 slender cylinder; I once visually estimated and wrote "squat cup shape 1.2:1", and the client judged the result as "still inaccurate").
Example wording:
The body is a slender cylinder, approximately 74mm tall and 39mm in diameter (height about 1.9 times the diameter), with a black matte satin finish… - Ironclad rule for messaging (user correction on 2026-09-15): Lines/voiceover/stylized text must only cite official promotional material verbatim (folders, main image text).
❌ The "selling points" field in the attribute table ≠ official messaging (internal descriptions); ❌ Claims heard from reference samples/competitor videos must not be used as messaging (HSQ1 test: "egg-sized" is banned);
🟡 Size-related comparative terms (e.g., "thumb height") can only be used for visual proportion/comparison objects, not in messaging.
→ Before writing lines, first extract official messaging using
product-spec-extraction; do not write selling points from memory. - Results first (user decision on 2026-09-15): Video production prioritizes results; do not compromise visual quality for cost savings.
- If there is output, must proactively report progress; for long workflows, provide segmented progress updates; do not wait for follow-up.
- During the design phase, write all real selling points; do not delete them due to "lack of evidence" (proof is the placement team's responsibility); for restricted terms/efficacy claims, only issue warnings without blocking.
- Cost-sensitive: Use free quotas/low-cost options to validate before scaling up; state unit price before spending money.
Related Skills
clipforge-video-pipeline: Complete recipe for image stitching solutions (clipforge / MoneyPrinterTurbo) = Path ④, includes environment installation pitfalls, shot-by-shot image placement, local asset mode, and the 0-cost "real product dynamic clip library."
📚 Knowledge Base Index (8 Documents)
| When to Read | Document |
|---|---|
| Product looks wrong / deformed / discolored / size and proportion / mesh | references/product-fidelity.md |
| Choosing an engine / model fields / pricing | references/engines-and-models.md |
| Resolution / billing / arrears troubleshooting / pre-checks | references/resolution-cost-and-arrearage.md |
| Main pipeline / assembly / delivery verification | references/pipeline-assembly-and-qc.md |
| Completion rate / hook variations / performance metrics | references/hooks-and-ad-metrics.md |
| Voiceover / subtitles / timbre | references/voice-and-subtitles.md |
| Portrait rights / compliance red lines / reference image standards | references/compliance-portrait-and-references.md |
| Scene and story videos / realistic shooting techniques / storyboard wording | references/scene-drama-and-candid-style.md |