Puffin Ship Docs

broll_imagen_generate

AI agent that generates still images with Google Imagen and adds subtle motion (zoom/pan), then places them as broll clips in timeline gaps.

Tip: The media processor's imagen preset generates the same kind of clips from a spec, and with source: gaps fills empty spans. This processor remains the transcript-driven agent that writes its own prompts. See media and Filling gaps and generating per segment.

When to use

An alternative to broll_veo_generate when you want still images with motion rather than fully generated video. Images are faster and cheaper to generate. See the Broll guide.

In the editor

Add it from the Library (B-Roll group), or with + add step and a search for broll_imagen_generate, after your transcript and your main cut.

Under Inputs, add transcript as a step input, and backbone as a step input pointing at the step that made the cut, so that changing the cut makes this step think again rather than reusing pictures made for a different edit. Use the step's Prompt to say what the images should be like; that instruction is what steers them. max_generate is your budget for the run, target_dur_sec how long each image is held, and motion_style with zoom_pct or pan_pct give the stills their slow drift. eval_prompt is the standard each generated image is judged against, and images that fail it are thrown away rather than used.

This step needs your own Google key. Add it in the workspace's Variables & Service API Keys, from the editor's Settings. A run that needs a key you have not set is stopped before it starts, so you are not charged for half a video.

The images appear as clips on the b-roll level in the run timeline, filling the gaps where you are not on screen, and the generated files are saved into your project so you can reuse them. Preview before shipping: generated images are convincing at a glance and odd on a second look.

YAML Example

- id: broll_img
  processor: broll_imagen_generate
  input:
    - id: transcript
      step: transcribe_main
    - id: backbone
      step: ai_cut
  params:
    backbone_step: ai_cut
    max_generate: 8
    target_dur_sec: 4.0
    motion_style: zoom_in
    zoom_pct: 8
    output_dir: broll-imagen
    eval_prompt: >
      Accept: clear, focused image without distortion or artifacts.
      Reject: blurry, faces, text artifacts, impossible geometry.
  output:
    timeline: broll
  prompt: |
    Generate images for unfilled gaps that illustrate what the speaker is saying.
    Prefer clean, literal, on-topic visuals; avoid faces and text.
  cache: true

Required secrets

GOOGLE_API_KEY: set in workspace or template secrets. A run whose pipeline includes this processor is refused before it starts if the key is missing; the web UI prompts for it.

Inputs

ID Source Description
transcript step Word-level timestamps
backbone step (optional) Cache dep: re-run when cut changes

Params

Param Type Default Description
min_gap_sec duration (s) 5 Minimum gap to fill
max_gap_sec duration (s) 0 Gaps longer than this need coverage (0 = AI decides)
max_duration_sec duration (s) 0 Max clip duration
target_dur_sec duration (s) 4 Target clip duration
motion_style select: zoom_in, zoom_out, pan_left, pan_right, none "zoom_in" "zoom_in", "zoom_out", "pan_left", "pan_right", "none"
zoom_pct number 5 Zoom percentage for zoom motion styles
pan_pct number 10 Pan percentage for pan motion styles
eval_prompt text none Accept/reject criteria for generated image analysis
no_clip_reuse bool false Prevent reusing the same image in multiple gaps
model select: imagen-4.0-generate-001, imagen-3.0-generate-002 "imagen-4.0-generate-001" Imagen model name override
max_generate number 0 Imagen budget per run (0 = unlimited)
backbone_step string none Step ID to read backbone timeline from
output_dir string "broll-imagen" Folder in your workspace where generated clips are kept.

Output

EditDecisions on the broll level.

Notes

  • Uses Puffin Ship's built-in AI for prompt generation; requires a GOOGLE_API_KEY (set in your workspace's Service API Keys) for Imagen generation.
  • Generated images are saved into your workspace, in the folder named by output_dir (e.g. broll-imagen/), and tracked in a manifest.
  • Motion is added as a slow zoom and pan across the still image.