Veo 3.1 JSON Reference: Complete Schema Documentation

The definitive technical guide for AI video prompt engineering

I've spent the last month treating Veo 3.1 like an undocumented API. While others were experimenting with adjectives, I was mapping parameters. What emerged is the most complete schema reference available for Google's video generation model—tested across 300+ generations, validated against actual behavior, and organized for developers who need reliable, repeatable results.

This isn't a tutorial. It's documentation. Use it to build tools, automate workflows, or simply understand why your prompts behave the way they do.

---

Schema Overview

Veo 3.1 accepts a JSON object with five primary sections. Three are required. Two are optional but strongly recommended for production work.

{
  "cinematography": {},    // REQUIRED: Camera behavior
  "subject": {},           // REQUIRED: What's in frame
  "environment": {},        // REQUIRED: Context and atmosphere
  "motion": {},            // OPTIONAL: Temporal logic and physics
  "negative_prompts": []   // OPTIONAL: Exclusion criteria
}

The parser is stricter than typical JSON validators. Trailing commas break silently. Type mismatches fail without error messages. This reference includes validation rules I've discovered through systematic error testing.

---

cinematography: Complete Specification

Controls camera type, movement, lens characteristics, and framing.

Camera Type

Value	Behaviour	Use Case
drone	Aerial perspective, unlimited movement range	Establishing shots, landscapes
handheld	Slight organic shake, responsive feel	Documentary, intimate scenes
tripod	Locked position, absolute stability	Interviews, static compositions
gimbal	Smooth motion compensation	Tracking shots, walking sequences
crane	Vertical arc movement, dramatic elevation	Reveals, sweeping transitions
dolly	Horizontal rail movement, precise positioning	Cinematic tracking, product shots

Validation: String enum. Case-sensitive. `Drone` fails. `drone` succeeds.

Movement Object

{
  "type": "dolly_in",
  "speed": "slow",
  "easing": "ease_in_out",
  "duration_seconds": 4
}

Movement Types

Type	Axis	Behaviour
static	None	No camera movement
pan_left / pan_right	Horizontal rotation	Camera rotates on vertical axis
tilt_up / tilt_down	Vertical rotation	Camera rotates on horizontal axis
truck_left / truck_right	Horizontal translation	Camera moves sideways without rotation
dolly_in / dolly_out	Z-axis translation	Camera moves toward/away from subject
descend / ascend	Vertical translation	Elevation change (drone/crane specific)
push_in / pull_out	Z-axis with subtle zoom	Hybrid movement, cinematic feel
orbit_cw / orbit_ccw	Circular path	360° rotation around subject

Speed Values

Value	Approximate Rate	Best For
very_slow	0.5× base	Contemplative, atmospheric
slow	0.75× base	Standard cinematic
medium	1.0× base	Natural movement
fast	1.5× base	Action, energy
very_fast	2.0× base	Dynamic transitions

Critical Discovery: Speed interpretation varies by movement type. `slow` on a dolly_in produces different perceived velocity than `slow` on a pan_left. Test with your specific combination.

Easing Functions

Value	Curve	Visual Effect
linear	Constant velocity	Mechanical, unmotivated
ease_in	Acceleration	Settling into movement
ease_out	Deceleration	Arriving at rest
ease_in_out	S-curve	Natural, motivated movement

Default: If omitted, Veo 3.1 applies `ease_in_out` for most movements. Explicit declaration recommended for predictable results.

Lens Object

{
  "focal_length": "24mm",
  "aperture": "f/2.8",
  "focus_distance": "subject"
}

Focal Length

Accepts string with unit: `"16mm"`, `"24mm"`, `"35mm"`, `"50mm"`, `"85mm"`, `"135mm"`.

Behavior Mapping:

Focal Length	Field of View	Perspective Distortion	Typical Use
16mm	Ultra-wide	Exaggerated depth	Architecture, immersive
24mm	Wide	Natural, expansive	Establishing shots
35mm	Standard	Slight wide feel	Documentary, walkthrough
50mm	Normal	Human eye approximation	Neutral, versatile
85mm	Short telephoto	Compressed depth	Portraits, isolation
135mm	Telephoto	Flattened perspective	Detail extraction, intimacy

Validation: Must include `mm` suffix. Numeric values alone fail parsing.

Aperture

Accepts: `"f/1.4"`, `"f/2"`, `"f/2.8"`, `"f/4"`, `"f/5.6"`, `"f/8"`, `"f/11"`, `"f/16"`.

Depth of Field Effect: Lower f-values produce shallower focus. However, Veo 3.1's bokeh implementation is less reliable than physical optics. Test before depending on selective focus for critical shots.

Focus Distance

Value	Behavior
"subject"	Primary subject in focus
"foreground"	Nearest element sharp
"background"	Distant plane sharp
"infinity"	Everything beyond 10m sharp
Specific distance: "2.5m"	Explicit focal plane

---

subject: Entity Specification

Defines what appears in frame. Supports single subjects or hierarchical compositions.

Basic Structure

{
  "primary": {
    "type": "character",
    "description": "woman_in_trench_coat",
    "attributes": ["confident_posture", "wind_in_hair"],
    "action": "walking_toward_camera"
  },
  "secondary": {
    "type": "environment",
    "description": "rainy_street",
    "attributes": ["neon_reflections", "wet_pavement"]
  }
}

Type Categories

Type	Description	Attribute Examples
character	Human or humanoid figure	confident_posture , determined_expression , casual_clothing
object	Inanimate focal point	metallic_surface , vintage_design , product_packaging
environment	Setting or background	urban_density , natural_landscape , architectural_detail
abstract	Non-representational forms	flowing_geometry , particle_system , color_field

Action Specification

Actions use verb_noun format with optional modifiers:

Pattern	Example	Result
verb_target	walking_toward_camera	Clear directionality
verb_state	standing_still	Static pose
verb_modifier	running_urgently	Emotional quality

Temporal Consistency: For multi-scene sequences, use identical `description` strings with modified `action` values. Veo 3.1 attempts visual continuity when subject descriptions match exactly.

---

environment: Context Control

Specifies setting, lighting, atmosphere, and temporal conditions.

Complete Structure

{
  "location": {
    "type": "urban",
    "description": "tokyo_alleyway",
    "era": "near_future"
  },
  "time_of_day": "night",
  "lighting": {
    "key_light": "neon_blue_sign",
    "fill_light": "ambient_moonlight",
    "rim_light": "none",
    "practical_sources": ["vending_machine_glow", "distant_headlights"]
  },
  "atmosphere": {
    "weather": "light_rain",
    "mood": "melancholic_noir",
    "particulates": ["mist", "steam_from_vents"]
  }
}

Location Types

Type	Era Options	Description Focus
urban	contemporary , near_future , retro , cyberpunk	Density, architecture, signage
natural	untouched , cultivated , wilderness , garden	Terrain, vegetation, scale
interior	modern , historic , industrial , domestic	Space definition, materials, light sources
abstract	minimal , surreal , geometric	Spatial logic, color fields, form

Lighting System

Veo 3.1's lighting parser recognizes specific descriptive patterns:

Light Type	Effective Descriptions	Avoid
key_light	moonlight_cool , sunset_warm , neon_pink , streetlamp_orange	Vague: bright , soft
fill_light	ambient_bounce , shadow_softening , reflected_neon	Unspecified sources
rim_light	hair_light , edge_separation , contour_highlight	Generic: backlight
practical_sources	Array of motivated lights visible in frame	Unmotivated illumination

Discovery: Lighting descriptions work best when they specify color temperature and motivation. `moonlight_cool` produces different results than `blue_light` because the parser associates the former with specific environmental context.

Atmosphere Parameters

Parameter	Values	Visual Effect
weather	clear , cloudy , light_rain , heavy_rain , fog , mist , snow	Environmental conditions
mood	optimistic , tense , melancholic , energetic , serene , noir	Color grading bias
particulates	Array: dust_motes , steam , smoke , mist , pollen , ash	Atmospheric depth, light interaction

---

motion: Temporal Logic

Optional but critical for sequences requiring physical consistency or specific timing.

Structure

{
  "temporal_logic": "continuous",
  "physics": "realistic",
  "speed_ramp": "constant",
  "motion_blur": "natural"
}

Temporal Logic Modes

Mode	Behaviour	Use Case	Current Reliability
continuous	Smooth, unbroken motion	Camera movements, tracking	⭐⭐⭐⭐⭐ Highly reliable
discrete	Cut-like transitions	Scene changes, time jumps	⭐⭐⭐⭐ Stable
loop	Repeating cycles	Background elements, effects	⭐⭐⚠️ Erratic in current build

Warning: `loop` with camera movements produces unpredictable results in Veo 3.1 as of February 2026. Avoid for production work or test extensively.

Physics Models

Model	Behavior	Best For
realistic	Gravity, inertia, momentum affect motion	Grounded, physical world
fluid	Reduced physical constraints, flowing motion	Abstract, dream sequences
snappy	Immediate response, reduced weight	UI animations, energetic cuts
ethereal	Slowed time, floating quality	Atmospheric, contemplative

Speed Ramp

Value	Curve	Application
constant	No change	Standard movement
ramp_in	Acceleration	Starting motion
ramp_out	Deceleration	Stopping motion
ramp_in_out	S-curve	Smooth start/stop

---

negative_prompts: Exclusion Criteria

Array of strings specifying what to avoid. Critical for preventing common AI video artifacts.

High-Impact Negatives

Category	Effective Negatives	Problem Solved
Style	anime , cartoon , 3d_render , cgi , video_game	Maintains photorealism
Quality	blurry , low_resolution , compression_artifacts , noise	Output fidelity
Temporal	flickering , judder , inconsistent_lighting , morphing	Frame-to-frame stability
Content	text , watermark , logo , signature	Clean output
Anatomy	deformed_hands , extra_fingers , mutated_limbs	Character integrity

Syntax: Simple string array. No nesting.

"negative_prompts": [
  "anime",
  "blurry",
  "flickering",
  "deformed_hands"
]

---

Multi-Scene Arrays: Advanced Sequences

For shots requiring continuity across cuts, Veo 3.1 supports scene arrays with explicit transition logic.

Structure

{
  "scenes": [
    {
      "scene_id": "01_establishing",
      "duration_seconds": 4,
      "cinematography": {},
      "subject": {},
      "environment": {},
      "transitions": {
        "from_previous": "hard_cut",
        "motion_blur": "none"
      }
    }
  ],
  "global_constraints": {
    "character_consistency": true,
    "lighting_continuity": "maintain_key_light_direction",
    "color_grading": "consistent_palette"
  }
}

Transition Types

Type	Behaviour	Use Case
hard_cut	Immediate change	Standard editing
match_cut	Visual element connects scenes	Creative transitions
dissolve	Gradual overlap	Time passage, memory
whip_pan	Fast blur transition	Energy, momentum
match_movement	Continues camera motion across cut	Invisible cuts

Global Constraints

Constraint	Options	Effect
character_consistency	true , false	Attempts visual continuity for matching descriptions
lighting_continuity	maintain_key_light_direction , maintain_color_temperature , none	Prevents jarring light changes
color_grading	consistent_palette , progressive_shift , scene_specific	Overall color management

Critical Implementation: For character consistency, `subject.primary.description` must match exactly across scenes. Veo 3.1 uses string matching, not semantic similarity. `woman_in_trench_coat` ≠ `woman_wearing_trench_coat`.

---

Validation & Debugging

Common Silent Failures

Symptom	Likely Cause	Solution
Output ignores camera direction	Misspelled cinematography key	Check spelling, verify nesting
Lighting flat despite specification	Invalid key_light description	Use tested enum values
Character morphs between scenes	continuity_from reference missing	Explicitly declare scene relationships
Motion speed inconsistent	speed value not in enum	Use very_slow , slow , medium , fast , very_fast
Generation fails without error	Trailing comma in JSON	Validate with strict linter

Testing Protocol

When debugging, use this minimal valid structure as baseline:

{
  "cinematography": {
    "camera_type": "tripod",
    "movement": { "type": "static" }
  },
  "subject": {
    "primary": { "type": "environment", "description": "test" }
  },
  "environment": {
    "time_of_day": "day"
  }
}

If this generates successfully, add complexity incrementally. If this fails, check account status or platform availability.

---

Schema Versioning

Veo 3.1's parser evolves. Parameters valid today may deprecate. This reference reflects build `2026.02.12`.

Change Tracking

Date	Change	Impact
2026.01.15	camera_movement deprecated, replaced with nested movement object	Update legacy prompts
2026.01.28	loop temporal logic reliability reduced	Avoid for production
2026.02.05	practical_sources added to lighting	New creative options
2026.02.12	motion_blur parameter added to transitions	Finer control

---

Implementation Tools

Live JSON Generator

I've built a tool that implements this schema with real-time validation, dropdown selectors for all enum values, and platform-specific guardrails. It eliminates syntax errors and provides immediate feedback on parameter combinations.

→ JSON Prompt Gen

Cinematic Terms Dictionary

Reference library mapping traditional filmmaking concepts to their JSON parameter equivalents. Search by technique, visual effect, or platform compatibility.

→ Cinematic Dictionary

---

Community & Updates

This documentation lives. As Veo 3.1 evolves, this reference updates. For real-time schema discussions, edge case reporting, or implementation questions:

• GitHub: Schema issues and feature requests

• Reddit: Daily user discussions and technique sharing

Found a parameter combination that behaves unexpectedly? That's valuable data. Share it. The schema map improves with every edge case reported.

---

License & Usage

This reference is independently researched and maintained. No affiliation with Google or DeepMind. Schema behavior observed through systematic testing, not official documentation.

Use freely. Build tools. Automate workflows. Commercial use permitted with attribution.

---

Last verified: February 18, 2026. Tested on Veo 3.1 build 2026.02.12.