Usage Guide

This guide covers the day-to-day workflows for using Renku: specifying inputs, discovering blueprints and models, testing with dry runs, generating content, and iterating on your creations.

Specifying Inputs

Every blueprint requires an inputs file that provides the configuration for your video generation.

Input File Format

Inputs are specified in YAML with two main sections:

inputs:
  InquiryPrompt: "Your topic or prompt here"
  Duration: 60
  NumOfSegments: 3
  # ... other blueprint-specific inputs

models:
  # Optional: override default model selections
  - model: minimax/speech-2.6-hd
    provider: replicate
    producerId: AudioProducer

Input Types

Type	YAML Syntax	Example
string	Quoted or unquoted text	"Hello world" or Hello world
int	Number without quotes	42
array	YAML list	["item1", "item2"]

Using Input Templates

Every blueprint includes an input-template.yaml with all available inputs and their defaults:

# Copy the template
cp {blueprint-dir}/input-template.yaml ./my-inputs.yaml

# Edit with your values
nano ./my-inputs.yaml

Model Selection

Select which AI model to use for each producer:

models:
  # Use a specific video model
  - model: google/veo-3.1-fast
    provider: replicate
    producerId: VideoProducer

  # Use a specific voice model with custom config
  - model: minimax/speech-2.6-hd
    provider: replicate
    producerId: AudioProducer

  # LLM producer with structured output
  - model: gpt-5-mini
    provider: openai
    producerId: ScriptProducer
    config:
      text_format: json_schema

The config field allows you to pass provider-specific configuration options.

Note: Input-to-provider field mappings (transforms) are defined in the producer YAML files, not in the input template. This keeps the input file simple - you only need to specify what model to use, not how inputs map to provider fields.

Discovering Content

Browsing Blueprints

Browse available blueprints in your workspace catalog:

ls ./catalog/blueprints/

Each blueprint directory contains:

• The blueprint YAML file with the workflow definition
• An input-template.yaml documenting required inputs and their types

Browsing Models

See available models for a blueprint’s producers:

renku producers:list --blueprint=video-only.yaml

Output:

Producer model configurations:

VideoProducer (4 video models)
  Provider    Model                          Price
  replicate   bytedance/seedance-1-pro-fast  480p: $0.015/s
  replicate   google/veo-3.1-fast            $0.10/s
  fal-ai      veo3-1                         -

AudioProducer (2 audio models)
  Provider    Model                 Price
  replicate   minimax/speech-2.6-hd $0.0001/token
  replicate   elevenlabs/v3         $0.0001/token

⚠️  Missing API tokens:
  - fal-ai: FAL_KEY not set

Testing with Dry Run

Before spending API credits, validate your configuration with a dry run:

renku generate \
  --inputs=./my-inputs.yaml \
  --blueprint=./my-blueprint.yaml \
  --dry-run

What Dry Run Does

• Validates blueprint YAML structure
• Checks all required inputs are provided
• Verifies producer paths exist
• Creates the execution plan
• Generates placeholder artifacts

What Dry Run Doesn’t Do

• Call any AI provider APIs
• Consume API credits
• Generate real content

Inspecting the Plan

After a dry run, examine the execution plan:

cat {workspace}/builds/movie-{id}/runs/rev-0001-plan.json

The plan shows:

• Execution layers (parallel groups)
• Jobs in each layer
• Input/output connections
• Canonical IDs for all nodes

Running Generation

Full Generation

Run the complete workflow:

renku generate \
  --inputs=./my-inputs.yaml \
  --blueprint=./my-blueprint.yaml

Renku will:

1. Create a new movie directory
2. Execute producers layer by layer
3. Store artifacts in the blob store
4. Create symlinks in artifacts/
5. Log all events for future reference

Continue an Existing Movie

Resume or regenerate an existing movie:

# By movie ID
renku generate --movie-id=movie-a1b2c3d4 --inputs=./inputs.yaml

# The most recent movie
renku generate --last --inputs=./inputs.yaml

Note: The --inputs flag is always required, even when continuing an existing movie. This ensures model selections are available for any jobs that need to run.

Non-Interactive Mode

Skip confirmation prompts for automation:

renku generate \
  --inputs=./my-inputs.yaml \
  --blueprint=./my-blueprint.yaml \
  --non-interactive

Finding Your Outputs

Generated content is in two locations within your current working directory:

Build directory (builds/movie-{id}/):

• blobs/ - Raw generated files
• manifests/ - Artifact metadata
• events/ - Execution logs

Artifacts view (artifacts/movie-{id}/):

• Human-readable filenames
• Symlinks to blob storage
• Easy to browse and share

Use renku list to see all builds in the current project.

Editing Workflow

Renku’s incremental build system makes iteration efficient.

Changing Inputs

1. Edit your inputs file
2. Re-run generation on the same movie:

renku generate --movie-id=movie-a1b2c3d4 --inputs=./my-inputs.yaml

Renku detects which inputs changed and only regenerates affected artifacts.

Editing Generated Prompts

You can manually edit generated text artifacts:

1. Find the artifact in artifacts/movie-{id}/
2. Edit the file directly (it’s a symlink to the blob)
3. Re-run generation:

renku generate --movie-id=movie-a1b2c3d4 --inputs=./inputs.yaml

Renku will:

• Detect your manual edits
• Keep your changes
• Only regenerate downstream artifacts that depend on the edited file

Replacing Artifacts

If an AI-generated image or video isn’t satisfactory:

1. Replace the file in artifacts/movie-{id}/
2. Re-run generation

Your replacement will be used for downstream processing (like timeline composition).

Layer-by-Layer Generation

For cost control and quality review, generate content in stages.

What Are Layers?

Renku groups independent jobs into execution layers:

• Layer 0: Script generation (depends only on inputs)
• Layer 1: Prompt generation, audio synthesis (depends on script)
• Layer 2: Video/image generation (depends on prompts)
• Layer 3: Timeline composition (depends on all media)

Generate Up to a Specific Layer

renku generate \
  --inputs=./my-inputs.yaml \
  --blueprint=./my-blueprint.yaml \
  --up-to-layer=1

This stops after layer 1, so you can:

• Review the generated script
• Check audio quality
• Make edits before generating expensive video content

Continue to Next Layers

After reviewing, continue generation:

renku generate --movie-id=movie-a1b2c3d4 --inputs=./inputs.yaml --up-to-layer=2

Re-Run From a Specific Layer

If you need to regenerate content from a specific layer onwards (e.g., after changing model settings or fixing an issue), use --re-run-from:

# Re-run from layer 2 (skips layers 0-1, uses existing artifacts)
renku generate --last --inputs=./inputs.yaml --from=2

This is useful when:

• You want to try a different video model without regenerating scripts
• A later layer failed and you want to retry from that point
• You’ve manually edited artifacts at a specific layer

The --from flag:

• Takes a 0-indexed layer number
• Skips all layers before the specified layer (uses existing artifacts)
• Forces all jobs at the specified layer and above to re-run
• Requires --inputs to be specified (for model selections)

You can combine --from with --up-to-layer to re-run a specific range:

# Re-run only layers 2 and 3
renku generate --last --inputs=./inputs.yaml --from=2 --up-to-layer=3

Surgical Artifact Regeneration

When you need to regenerate just one specific artifact without affecting siblings, use --artifact-id:

# Regenerate only segment 2's audio (not segments 0, 1, 3, 4)
renku generate --last --artifact-id="AudioProducer.GeneratedAudio[2]" --inputs=./inputs.yaml

This is different from --from which regenerates all jobs at a layer. With --artifact-id:

• Only the specified artifact and its downstream dependencies are regenerated
• Sibling artifacts in the same layer are untouched
• You can combine with --up-to-layer to limit how far downstream propagation goes

When to use each:

Scenario	Use
One segment sounds wrong, others are fine	--artifact-id
Changed model settings, need to redo a layer	--from
Generated up to layer 1, now want to fix one image	--artifact-id + --up-to-layer
Need to retry all video generation	--from=N where N is the video layer

Finding artifact IDs:

# List all artifact IDs in a movie
cat builds/movie-{id}/manifests/rev-XXXX.json | jq '.artefacts | keys'

Note: Quote the artifact ID when using zsh to prevent bracket expansion:

renku generate --last --artifact-id="AudioProducer.GeneratedAudio[2]" --inputs=./inputs.yaml

Cost-Saving Strategies

1. Review scripts first - Script generation is cheap; video generation is expensive
2. Use layer limits - Generate expensive content only when you’re happy with cheaper precursors
3. Iterate on prompts - Edit video prompts before generating videos
4. Leverage caching - Re-running generation only rebuilds changed artifacts
5. Use --from for retries - If a later layer fails, use --from=N to retry from that layer without regenerating earlier content
6. Use --artifact-id for surgical fixes - If only one segment needs work, regenerate just that artifact instead of the whole layer

Viewing Content

Open in Viewer

Start the viewer and open a movie:

# Specific movie
renku viewer:view --movie-id=movie-a1b2c3d4

# Most recent movie
renku viewer:view --last

Background Viewer Server

Start the viewer server in the background:

renku viewer:start

Stop it when done:

renku viewer:stop

Exporting Video

Export the final video as MP4:

renku export --movie-id=movie-a1b2c3d4

With custom settings:

renku export --last \
  --width=1920 \
  --height=1080 \
  --fps=30

Choosing an Exporter

Renku supports two exporter backends:

Exporter	Description	Requirements
remotion	Docker-based Remotion renderer (default)	Docker Desktop
ffmpeg	Native FFmpeg renderer	FFmpeg installed

Use the --exporter flag to choose:

# Use FFmpeg (faster, no Docker required)
renku export --last --exporter=ffmpeg

# Use Remotion (default, requires Docker)
renku export --last --exporter=remotion

FFmpeg exporter advantages:

• No Docker installation required
• Faster rendering for simple timelines
• Produces MP3 for audio-only timelines
• Supports karaoke-style subtitles

Remotion exporter advantages:

• More advanced video effects
• Better suited for complex compositions

Advanced Export Configuration

For fine-grained control over export settings, use a YAML config file:

renku export --last --inputs=./export-config.yaml

Example config file with all available options:

# Video settings
width: 1920
height: 1080
fps: 30
exporter: ffmpeg

# FFmpeg encoding settings
preset: medium      # ultrafast, fast, medium, slow
crf: 23             # Quality: 0-51 (lower = better)
audioBitrate: 192k  # Audio quality

# Karaoke-style subtitles (requires TranscriptionProducer)
subtitles:
  font: Arial
  fontSize: 48
  fontBaseColor: "#FFFFFF"
  fontHighlightColor: "#FFD700"
  backgroundColor: "#000000"
  backgroundOpacity: 0.5
  bottomMarginPercent: 10
  maxWordsPerLine: 4
  highlightEffect: true

Subtitles

If your blueprint includes a TranscriptionProducer, the FFmpeg exporter can add karaoke-style subtitles that highlight words as they’re spoken:

1. Ensure your blueprint has a TranscriptionProducer that generates word-level timestamps
2. Create an export config with subtitle settings
3. Run export with the config file

The exported video is saved to:

• builds/movie-{id}/FinalVideo.mp4
• artifacts/movie-{id}/FinalVideo.mp4 (symlink)

Cleaning Up

List builds in the current project:

renku list

This shows which builds have artifacts (completed runs) vs. dry-run only builds.

Remove dry-run builds (safe default):

renku clean

Remove a specific movie:

renku clean --movie-id=movie-a1b2c3d4

Remove all builds including completed ones:

renku clean --all

Tips and Best Practices

Start Small

For new blueprints, start with:

• Fewer segments (2-3 instead of 10)
• Dry run first
• Layer-by-layer generation

Review at Each Stage

Don’t generate everything at once:

1. Generate script → Review
2. Generate prompts → Review and edit
3. Generate media → Review
4. Compose timeline → Export

Use Version Control

Keep your inputs files in version control:

• Track changes to prompts and settings
• Reproduce past generations
• Share configurations with team members

Monitor Costs

Check provider dashboards regularly:

• Video generation is most expensive
• Audio generation is moderate
• Script generation is cheap

Use renku producers:list to see pricing information.