create-video-veo3

name	create-video-veo3
description	create cinematic product videos using google veo 3.1 via the higgsfield mcp. use as the default workhorse for ads, talking-head with native synced dialogue, vertical social, and any clip where prompt adherence and audio quality matter more than raw motion drama. supports 4-8s clips at 16:9 or 9:16.

create-video-veo3

Purpose

Generate a single cinematic short clip with Google Veo 3.1 (the veo3_1 Higgsfield model) from a prompt and an optional start image. Veo 3.1 is the default workhorse for high-quality product video: best-in-class native audio + lip-sync, strong prompt adherence, "ad-bright" aesthetic, true 4K available via the ultra quality tier.

Use this atom when:

• The brief calls for a polished, broadcast-grade ad clip.
• Native synced dialogue or ambient audio is required in one pass.
• A reference start image (product still, brand frame) should drive the motion.
• The clip needs to be 4–8 seconds at 16:9 or 9:16.

Prefer create-video-kling for multi-shot dialogue scenes, create-video-seedance for complex camera moves with reference media, and create-video-grok for X-native meme content.

Decision rules

Default model variant: veo-3-1-preview, not veo-3-1-fast. The fast model passes prompts through a silent enhancer that rewrites verb-led kinetic prompts into "8-section bureaucratic specs" that produce slow/static output. preview preserves the verb-led intent. Validated on The Feed v1, Pair Eyewear v01, multiple production runs. See skills/orchestrators/higgsfield/i2v-prompting-learnings.md Part 2 + memory feedback_veo_via_higgsfield.

Always verb-led prompts. CHARACTER+VERB in first 8 words. ACTION verbs in CAPS. Quantified motion magnitudes (STRIDES forward 3 paces in 2 seconds, not walks slowly). Banned vocab: static, locked, subtle, near-static, slow, smooth, gentle, dreamy, ethereal, Vermeer-coded, imperceptibly, holds, drifts. Use _shared/build_animation_prompt.py or follow its shape verbatim. See memory feedback_i2v_kinetic_prompts.

Product B-roll rule: camera-only motion on locked subject. Veo 3.1 hallucinates product label content when asked to rotate, orbit, tumble, or flip a product (model has never seen the unseen sides; it invents fake text). For product hero shots use camera-only moves on a LOCKED subject:

• ✅ Push-in, pull-back, crash zoom (camera moves toward/away from static product)
• ✅ Vertical track-up (camera tilts along front face — product doesn't rotate)
• ✅ Light/atmosphere motion (light streaks, particles past locked product)
• ❌ 360 orbit, tumble, flip, rotation around vertical axis
• ❌ Complex physics (snap-drop with bounce → landing position diverges from prompt)

Pair with neutral BG (off-white seamless gradient or brand-color flat) — setting-specific BGs split Veo's rendering budget and cause label drift. See memory feedback_veo_no_rotation_product.

Framing scale for creator activity scenes: Default wide distance shot (~6-10m, full body, environmental, deep focus) — NOT MS chest-up. MS chest-up + AI face + motion reads as "treadmill jog with portrait bokeh." See CAMERA_STYLES.md § Framing scale guidance and memory feedback_distance_shot_for_activity. The creator keyframe itself comes from create-ugc-higgsfield; Veo just animates from it.

Camera register lock: Default is UGC-iPhone-Realtime per CAMERA_STYLES.md. Every i2v prompt MUST contain the iPhone-1x + wide-DOF + handheld + real-skin vocab block. Banned-vocab list is a hard reject. Override only when brief explicitly calls for Cinematic-Shallow-DOF.

On Higgsfield moderation reject: STOP and surface to user. Do NOT auto-fallback to FAL. The user wants visibility into what's getting flagged before any model swap. See memory feedback_hf_moderation_surface. (Overrides the documented "2 rejects → FAL" auto-rule from i2v-prompting-learnings.md.)

Veo minimum duration is 4 seconds (allowed: 4 / 6 / 8). For target display durations shorter than 4s, render at 4s and trim in post via ffmpeg (-t T -i clip.mp4). For ~1.5s hero shots, ensure the kinetic motion happens in the first ~1-2s of the prompt so the trim captures the action — Veo defaults to gradual reveal otherwise.

Speedup in post for tighter Reels pace. Veo's "real-time" interpretation skews leisurely. Default to setpts=PTS/1.2 for any clip that needs Reels energy; push to 1.5x only when the motion is brief and discrete (door open, head lift). Don't apply 1.5x to inherently kinetic motion like running — it looks cartoonish. Per memory feedback_ffmpeg_t_placement: put -t BEFORE -i when using setpts so the speed filter actually compresses.

Inputs

• A clear video brief with: subject, action, visual style, camera direction, mood, audio direction.
• Optional start_image path or URL (Higgsfield medias parameter, role start_image).
• Aspect ratio: 16:9 or 9:16.
• Duration: 4, 6, or 8 seconds.
• Quality tier: basic | high | ultra (default basic for iteration, ultra for finals).
• Model variant: veo-3-1-fast (default) or veo-3-1-preview (higher fidelity, slower).
• Output directory or test-run directory.

Workflow

1. Read the brief and confirm subject, action, style, camera, mood, and audio cues are present.
2. Compose the prompt. Use skills/atoms/video-generation/_shared/build_animation_prompt.py to enforce the character-action-verb-led shape: <subject> <ACTION-VERB>. <camera/secondary motion>. <style>. NEGATIVE: <cues>. Camera-first prompts produce zoom-on-a-still output; lead with the verb so the model animates the subject, not just the frame.
3. If a start image is provided, upload it via mcp__higgsfield__media_upload and confirm with mcp__higgsfield__media_confirm.
4. Call mcp__higgsfield__generate_video with model="veo3_1", prompt, aspect_ratio, duration, quality, model variant, and medias if applicable.
5. Poll mcp__higgsfield__job_status until complete; download the resulting MP4 to the output directory.
6. Write manifest.json with provider: "Higgsfield", model_or_tool: "veo3_1", output paths, status, errors, warnings.
7. Run the verifier in tests/verifier.md.

Output

• Primary: one MP4 clip at the requested aspect ratio and duration.
• manifest.json matching the standard schema in TESTING_RULES.md.
• verification.md naming the checks performed.

Quality Checks

• File exists, plays end-to-end, duration within ±0.5s of requested.
• Aspect ratio matches the request.
• Audio is present when the prompt asked for dialogue or ambient sound.
• No severe artifacts (frame tearing, watermarks, garbled text).
• Prompt adherence: subject and action are visible.
• Manifest paths resolve to real files.

Failure Modes

• Higgsfield credentials missing or invalid — return manifest with status: "blocked" and a clear message.
• 8-second cap — Veo 3.1 will not generate longer single clips; chain via create-video-seedance (up to 15s) or stitch with stitch-videos-ffmpeg.
• Rate limit (10 req/min) — backoff and retry once before failing.
• "Ad-bright" aesthetic mismatch — for moody/film-grit looks, route to a future Sora 2 Pro atom or use Cinema Studio Video v2 with genre: "noir".
• Start image rejected — re-upload at supported dimensions; Higgsfield prefers ≤4096px on the longest edge.
• Vague prompt → generic output — fail with a warning that the brief lacks subject/action specificity rather than burning credits silently.

Seedance content-filter inverse-fallback

When the orchestrator's first choice was Seedance and that run hit ip_detected / nsfw, the recommended retry is veo3_1_lite. See create-video-seedance/SKILL.md § "Content-filter auto-fallback" for the trigger surfaces and the recommended retry shape — the same prompt + medias usually clears Veo's filter on the first try. No special argument is needed here; the agent just sets model="veo3_1_lite" instead of seedance_2_0 and Veo's looser NSFW filter does the work.

Higgsfield CLI route (preferred when MCP unavailable)

When MCP tools are not registered in the session but the Higgsfield CLI is installed (/opt/homebrew/bin/higgsfield), use the CLI directly — this is the preferred fallback before FAL. See memory reference_higgsfield_cli.md for auth setup.

/opt/homebrew/bin/higgsfield generate create veo3_1 \
  --prompt "..." \
  --image /path/to/keyframe.png \
  --aspect_ratio 9:16 \
  --duration 4 \
  --quality high \
  --wait --wait-timeout 12m

Important flag gotcha (Veo 3.1 specifically): Veo 3.1 accepts --image for the input keyframe — NOT --start-image. Kling 3.0 uses --start-image and --end-image. If you pass --start-image to Veo 3.1 the CLI errors with "Error: Model accepts only --image." Confirmed during Blume video-01 production (2026-05-14).

The --wait flag blocks and prints the result CDN URL on the last line. Pipe through tail -1 to capture, then curl -sSL "$URL" -o /path/to/clip.mp4.

Cost (Higgsfield credits via CLI): veo3_1 high tier = ~22 credits/$0.44; veo3_1_lite = 8 credits/$0.16; seedance_2_0 = 22.5 credits/$0.45; kling3_0 = 10 credits/$0.20.

FAL fallback (known broken as of 2026-05-14)

⚠️ The FAL endpoint fal-ai/veo3/image-to-video was returning 422 Unprocessable Entity for all duration values during the Blume video-01 production. Do not retry blindly. Prefer the Higgsfield CLI route above. If FAL is the only option and it fails, surface to the user before falling back to Kling — never silently downgrade tiers. See memory feedback_veo_via_higgsfield.md.

Original FAL invocation:

python3 skills/atoms/video-generation/create-video-veo3/scripts/generate-fal.py \
  --prompt "..." \
  --output /path/to/clip.mp4 \
  --start-image /path/to/keyframe.png \
  --aspect-ratio 9:16 \
  --duration 4 \
  [--fast]

Model mapping:

• Higgsfield veo3_1 → fal-ai/veo3/image-to-video (full quality)
• Higgsfield veo3_1_lite → fal-ai/veo3/fast/image-to-video (pass --fast)

The manifest's provider field is set to "fal" (not "Higgsfield") when the fallback fires. See skills/atoms/_shared/fal_helpers.py for the shared upload/subscribe pattern.

Relevant memories (cross-reference before invoking)

Production-tested rules that should be applied before firing Veo i2v:

Memory	Rule
feedback_veo_via_higgsfield	Default i2v = veo3_1 via Higgsfield CLI; FAL Veo3 endpoint broken (422). On unavailability, surface — do NOT silently fall back to Kling.
feedback_veo_no_rotation_product	No rotation on products — camera-only on locked subject. 360 orbit / tumble fabricates label text.
feedback_i2v_kinetic_prompts	Verb-led prompts, CHARACTER+VERB in first 8 words, banned-vocab list, quantified magnitudes.
feedback_camera_style_default	Default register = UGC-iPhone-Realtime. Override only for cinematic spec ads.
feedback_distance_shot_for_activity	Wide distance shot for activity scenes (running, walking, biking) — full body, ~6-10m, environmental.
feedback_hf_moderation_surface	On any Higgsfield moderation reject, STOP and surface. No auto-FAL fallback.
feedback_ffmpeg_t_placement	-t BEFORE -i for setpts speedup; AFTER -i for output-side trim.
reference_higgsfield_veo_cli_flags	Veo 3.1 uses --image (not --start-image). --duration ∈ {4, 6, 8}.
reference_higgsfield_marketing_studio_broken	Marketing Studio is broken on Plus plan — skip MS, use Veo direct.
feedback_veo_spray_nozzle_prior	Spray = nozzle prior on atomizer products — use Seedance 2.0 for spray shots.

Production-tested patterns

Product hero B-roll (validated The Feed v3.2, Touchland v01):

• NB keyframe with real product PNG ref on neutral BG (off-white seamless)
• Camera-only Veo motion: crash zoom in, vertical track-up, or slow pull-back
• 4s native clip, trim to 1.3-2.0s in post for tight Reels pace

Creator-in-activity (validated The Feed v3.2 S07, Pair Eyewear v01):

• Soul keyframe via create-ugc-higgsfield — WIDE distance framing, iPhone-1x, deep focus
• Veo i2v with verb-led running/walking/striding prompt
• Trim to ~2.0-2.5s in post; apply setpts=PTS/1.2 if pace needs tightening

Sync-beat hand POV (validated The Feed v3.2 S04 S08 S12, Touchland v01):

• NB keyframe with real product PNG ref + slim female forearm description
• Veo i2v with hand-action verb (POURS, RIPS, TIPS) + product motion (cascade, tear, drop)
• Trim to action duration only (1.2-2.0s); avoid post-action awkward frames

Diptych/duplicate-frame artifact (Soul prior): When Soul renders a stacked duplicate image as keyframe, crop to one panel via PIL before feeding to Veo. Re-rolling Soul rarely fixes — composition triggers the prior consistently. Validated The Feed v3.2 S13.