create-video-kling

create-video-kling

Purpose

Generate a single dialogue-driven or multi-shot narrative clip with Kling 3.0 (the kling3_0 Higgsfield model). Kling 3.0's strengths are phoneme-level multi-character lip-sync, multi-shot scene reasoning, "filmed-not-rendered" physics, and the cheapest economics of the frontier engines.

Use this atom when:

• The clip has dialogue, especially with two or more speakers.
• A multi-shot beat (cut between two framings) needs to feel coherent.
• The aesthetic is character-driven, anime/stylized, or narrative-led.
• Cost matters and the clip can be 3–15 seconds.

Prefer create-video-veo3 for polished single-shot ads, create-video-seedance for product demos with reference media + camera moves, and create-video-grok for X-native meme content.

Inputs

• A clear video brief with: speakers, dialogue lines (per speaker), camera framing per shot, mood, audio direction.
• Optional start_image and/or end_image paths or URLs for first/last-frame conditioning. Note: start+end conditioning produces a morph between the two frames, not a literal camera-path interpolation. Useful for "world transforms around still subject" cuts; not useful for rotational moves (see Failure Modes). For complex camera paths, use a single start_image plus a prompt describing the move.
• Aspect ratio: 16:9, 9:16, or 1:1.
• Duration: 3 to 15 seconds.
• Mode: std (default) or pro (higher fidelity).
• Sound: on (default) or off.
• Output directory or test-run directory.

Workflow

1. Read the brief and confirm dialogue lines, framing per shot, and any start/end frames are present.
2. Compose the prompt. Lead with the scene framing, then character action and dialogue (quoted), then camera move, then audio direction.
3. If start/end images are provided, upload via mcp__higgsfield__media_upload and confirm with mcp__higgsfield__media_confirm.
4. Call mcp__higgsfield__generate_video with model="kling3_0", prompt, aspect_ratio, duration, mode, sound, and medias if applicable.
5. Poll mcp__higgsfield__job_status until complete; download the resulting MP4.
6. Write manifest.json with provider: "Higgsfield", model_or_tool: "kling3_0", 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.
• When dialogue was specified: lip-sync is plausible, audio matches the script.
• For multi-shot prompts: cuts are coherent, character identity persists across shots.
• No severe artifacts.
• Manifest paths resolve to real files.

Failure Modes

• Higgsfield credentials missing or invalid — return manifest with status: "blocked".
• 4+ speakers — Kling lip-sync degrades sharply; warn and recommend splitting into multiple clips.
• Long-clip identity drift — facial likeness can drift past ~10s; for >10s clips add a warning and consider chaining shorter clips with start/end frames.
• China data jurisdiction — flag in the manifest warnings for any client with data residency constraints.
• Vague dialogue prompt — if the brief lacks quoted lines, fail with a warning rather than letting Kling hallucinate dialogue.
• Aspect ratio not in [16:9, 9:16, 1:1] — reject with a clear error.
• start_image + end_image asked to render a camera rotation / barrel roll — Kling does NOT render a rotational camera path between two anchor frames. It crossfade-morphs: the visual content interpolates (environment dissolves, subject morphs) but the camera itself never rotates. This is useful for "world morphs around still subject" transformations but cannot deliver a literal roll. For true rotation: use create-video-veo3 with quality: high (better motion-prompt adherence) or generate a hard cut and apply FFmpeg rotate post-fx. Confirmed empirically — see LEARNINGS.md #19.
• FAL 403 Forbidden on rest.fal.ai/storage/auth/token (FAL path) — the start-image upload is being denied. After a burst of successful calls, a 403 here that persists through cooldown retries is an exhausted FAL balance, not a rate limit (429 is the rate limit; this 403 is not — cooldowns won't clear it). Top up at fal.ai/dashboard/billing and re-run; a transient "User is locked. Exhausted balance" can also self-recover on retry right after a top-up. Make multi-clip render scripts idempotent (skip already-rendered clips) so the re-run only regenerates what's missing.

FAL fallback

When the Higgsfield path fails, the orchestrator's generate_with_fallback.py router calls the sibling FAL script:

python3 skills/atoms/video-generation/create-video-kling/scripts/generate-fal.py \
  --prompt "..." \
  --output /path/to/clip.mp4 \
  --start-image /path/to/keyframe.png \
  [--end-image /path/to/end-frame.png] \
  --aspect-ratio 9:16 \
  --duration 5 \
  --mode std

⚠️ Version delta: Higgsfield ships Kling 3.0; FAL's latest as of 2026-05 is Kling 2.1. Outputs will differ — lip-sync quality and physics realism on Kling 2.1 are noticeably weaker. The fallback's meta.json includes a version_caveat field; the orchestrator surfaces this to the operator when fallback fires on a Kling scene.

Model mapping:

• Higgsfield kling3_0 mode=std → fal-ai/kling-video/v2.1/standard/image-to-video
• Higgsfield kling3_0 mode=pro → fal-ai/kling-video/v2.1/pro/image-to-video

If the version downgrade is unacceptable for a specific scene, the operator should pin <provider_override>=higgsfield and retry rather than accept the FAL Kling output.